Web API: The Good Parts

はじめに

1章　Web APIとは何か
    1.1 Web APIの重要性
        1.1.1　APIでの利用を前提としたサービスの登場
        1.1.2　モバイルアプリケーションと API
        1.1.3　APIエコノミー
    1.2 さまざまな APIのパターン
        1.2.1　公開しているウェブサービスのデータや機能の API公開
        1.2.2　他のページに貼り付けるウィジェットの公開
        1.2.3　モダンなウェブアプリケーションの構築
        1.2.4　スマートフォンアプリケーションの開発
        1.2.5　ソーシャルゲームの開発
        1.2.6　社内システムの連携
    1.3 何を APIで公開すべきか
        1.3.1　APIを公開するリスクはあるのか
        1.3.2　APIを公開することで得られるもの
    1.4 Web APIを美しく設計する重要性
        1.4.1　設計の美しい Web APIは使いやすい
        1.4.2　設計の美しい Web APIは変更しやすい
        1.4.3　設計の美しい Web APIは頑強である
        1.4.4　設計の美しい Web APIは恥ずかしくない
    1.5 Web APIを美しくするには
    1.6 RESTと Web API
    1.7 対象となる開発者の数と APIの設計思想
    1.8 まとめ

2章　エンドポイントの設計とリクエストの形式
    2.1 APIとして公開する機能を設計する
        2.1.1　モバイルアプリケーション向け APIに必要な機能
    2.2 API エンドポイントの考え方
        2.2.1　エンドポイントの基本的な設計
    2.3 HTTPメソッドとエンドポイント
        2.3.1　GETメソッド
        2.3.2　POSTメソッド
        2.3.3　PUTメソッド
        2.3.4　DELETEメソッド
        2.3.5　PATCHメソッド
    2.4 APIのエンドポイント設計
        2.4.1　リソースにアクセスするためのエンドポイントの設計の注意点
        2.4.2　利用する単語に気をつける
        2.4.3　スペースやエンコードを必要とする文字を使わない
        2.4.4　単語をつなげる必要がある場合はハイフンを利用する
    2.5 検索とクエリパラメータの設計
        2.5.1　取得数と取得位置のクエリパラメータ
        2.5.2　相対位置を利用する問題点
        2.5.3　絶対位置でデータを取得する
        2.5.4　絞り込みのためのパラメータ
        2.5.5　クエリパラメータとパスの使い分け
    2.6 ログインと OAuth 2.0
        2.6.1　アクセストークンの有効期限と更新
        2.6.2　その他の Grant Type
    2.7 ホスト名とエンドポイントの共通部分
    2.8 SSKDsとAPIデザイン
    2.9 HATEOASとREST LEVEL3 API
        2.9.1　REST LEVEL3 APIのメリット
        2.9.2　REST LEVEL3 API
    2.10 まとめ

3章　レスポンスデータの設計
    3.1 データフォーマット
        3.1.1　データフォーマットの指定方法
    3.2 JSONPの取り扱い
        3.2.1　JSONPをサポートする場合の作法
        3.2.2　JSONPとエラー処理
    3.3 データの内部構造の考え方
        3.3.1　レスポンスの内容をユーザーが選べるようにする
        3.3.2　エンベロープは必要か
        3.3.3　データはフラットにすべきか
        3.3.4　配列とフォーマット
        3.3.5　配列の件数、あるいは続きがあるかをどう返すべきか
    3.4 各データのフォーマット
        3.4.1　各データの名前
        3.4.2　性別のデータをどう表すか
        3.4.3　日付のフォーマット
        3.4.4　大きな整数と JSON
    3.5 レスポンスデータの設計
    3.6 エラーの表現
        3.6.1　ステータスコードでエラーを表現する
        3.6.2　エラーの詳細をクライアントに返す
        3.6.3　エラー詳細情報には何を入れるべきか
        3.6.4　エラーの際に HTMLが返ることを防ぐ
        3.6.5　メンテナンスとステータスコード
        3.6.6　意図的に不正確な情報を返したい場合
    3.7 まとめ

4章　HTTPの仕様を最大限利用する
    4.1 HTTPの仕様を利用する意義
    4.2 ステータスコードを正しく使う
        4.2.1　200番台:成功
        4.2.2　300番台追加で処理が必要
        4.2.3　クライアントのリクエストに問題があった場合
        4.2.4　500番台サーバに問題があった場合
    4.3 キャッシュとHTTPの仕様
        4.3.1　Expiration Model（期限切れモデル）
        4.3.2　Validation Model（検証モデル）
        4.3.3　Heuristic Expiration（発見的期限切れ）
        4.3.4　キャッシュをさせたくない場合
        4.3.5　Varyでキャッシュの単位を指定する
        4.3.6　Cache-Controlヘッダ
    4.4 メディアタイプの指定
        4.4.1　メディアタイプを Content-Typeで指定する必要性
        4.4.2　x-で始まるメディアタイプ
        4.4.3　自分でメディアタイプを定義する場合
        4.4.4　JSONや XMLを用いた新しいデータ形式を定義する場合
        4.4.5　メディアタイプとセキュリティ
        4.4.6　リクエストデータとメディアタイプ
    4.5 同一生成元ポリシーとクロスオリジンリソース共有
        4.5.1　CORSの基本的なやりとり
        4.5.2　プリフライトリクエスト
        4.5.3　CORSとユーザー認証情報
    4.6 独自の HTTPヘッダを定義する
    4.7 まとめ

5章　設計変更をしやすいWeb APIを作る
    5.1 設計変更のしやすさの重要性
        5.1.1　外部に公開している APIの場合
        5.1.2　モバイルアプリケーション向け APIの場合
        5.1.3　ウェブサービス上で使っている APIの場合
    5.2 APIをバージョンで管理する
        5.2.1　URIのバージョンを埋め込む
        5.2.2　バージョン番号をどう付けるか
        5.2.3　バージョンをクエリ文字列に入れる
        5.2.4　メディアタイプでバージョンを指定する方法
        5.2.5　どの方法を採用するべきか
    5.3 バージョンを変える際の指針
        5.3.1　常に最新版を返すエイリアスは必要か
    5.4 APIの提供を終了する
        5.4.1　ケーススタディ : Twitterの場合
        5.4.2　あらかじめ提供終了時の仕様を盛り込んでおく
        5.4.3　利用規約にサポート期限を明記する
    5.5 オーケストレーション層
    5.6 まとめ

6章　堅牢なWeb.APIを作る
    6.1 Web APIを安全にする
        6.1.1　どんなセキュリティの問題があるのか
    6.2 サーバとクライアントの間での情報の不正入手
        6.2.1　HTTPSによる HTTP通信の暗号化
        6.2.2　HTTPSを使えば 100%安全か
    6.3 ブラウザでアクセスする APIにおける問題
        6.3.1　XSS
        6.3.2　XSRF
        6.3.3　JSONハイジャック
    6.4 悪意あるアクセスへの対策を考える
        6.4.1　パラメータの改ざん
        6.4.2　リクエストの再送信
    6.5 セキュリティ関係の HTTPヘッダ
        6.5.1　X-Content-Type-Options
        6.5.2　X-XSS-Protection
        6.5.3　X-Frame-Options
        6.5.4　Content-Security-Policy
        6.5.5　Strict-Transpor t-Security
        6.5.6　Public-Key-Pins
        6.5.7　Set-Cookieヘッダとセキュリティ
    6.6 大量アクセスへの対策
        6.6.1　ユーザーごとのアクセスを制限する
        6.6.2　レートリミットの単位
        6.6.3　制限値を超えてしまった場合の対応
        6.6.4　レートリミットをユーザーに伝える
    6.7 まとめ

付録A　Web APIを公開する際にできること

付録B　Web .APIチェックリスト

索引

コラム目次
自分の情報へのエイリアス
その他のデータフォーマット
JSONPをサポートすべきか？
HTTP時間の形式
強い検証と弱い検証
バージョン番号を日付で表す
認証局が攻撃を受けて偽の証明書を発行してしまうケース
ブラウザからのアクセスを想定しないAPIの場合
実際のAPIの対応状況を見てみる
アクセス制限の緩和
レートリミットの実装