Web API The Good Partsを読んだが読書メモを残してなかったので復習がてらにポイントを書いておく。ただ、本のまとめとしては付録BのWebAPIチェックリストを活用すれば十分かもしれない。少々長くなったため前編・後編と分けた。
1.WebAPIの設計指針
本では指針として美しく設計することをあげていた。ここで言う美しさとは以下のことである。
- よく考えられている
- わかりやすく整理されている
- 無駄がない
では美しく設計するためにはどういう方針で望んだらよいのか? それは以下の原則に従うのが基本となる。
- 仕様が決まっているものに関しては仕様に従う
- 仕様が存在していないものに関してはデファクトスタンダードに従う
2.エンドポイント設計
2.1 API設計の基本
API設計の指針としては、公開するAPI がどのように使われるのかというユースケースをきちんと考えることがあげられる。そして、そのユースケースを元に「あるデータの集合」と「個々のデータ」をエンドポイントとして表現し、それに対して HTTP のメソッドで操作を表していくのがAPI設計の基本である。
例)
user
一覧取得:/usersにGET
新規作成:/usersにPOST
ユーザ情報取得:/users/id/にGET
ユーザ情報更新:/users/id/にPUT/PATCH
ユーザ情報削除:/users/id/にDELETE
2.2 エンドポイント設計の指針
エンドポイントとはAPIにアクセスするためのURIのことである。
エンドポイント設計の指針とは良いURIを設計することである。では良いURIとは何か? それは覚えやすく、どんな機能を持つURI なのかがひと目でわかるものである。
良いURIは以下のような特徴を持つ。
- 短く入力しやすい
- 人間が読んで理解できる
- 大文字小文字が混在していない → 基本はすべて小文字
- 改造しやすい(Hackable ) → 使い方を想像しやすい
- サーバ側のアーキテクチャが反映されていない → サーバの言語、構成によらない
- ルールが統一されている
2.3 エンドポイント設計で避けたほうがよいこと
以下にエンドポイント設計で避けた方がいい事項とその理由を示す。
- 単数形の名詞を利用するのはNG
- リソースの集合を表すので複数形の方がよい
- 動詞をエンドポイントに入れるのもNG
- URIはリソースを表すものなので名詞がよい
- 不適切な表現の単語を利用するのもNG
- 類似するAPIを参考にするとよい
- 参考:ProgrammableWeb(http://www.programmableweb.com/)
- スペースやエンコードを必要とする文字を使うのもNG
- エンドポイントがひと目でわからないようなものは避ける
- スペースもURI上は+に変換されるため避ける
- 単語をつなげる時に-(ハイフン)以外を使う
- ハイフンでつなげるのが今の主流
3.リクエスト形式
3.1 検索とクエリパラメータの設計
WebAPIによる検索ではGETを使用するが、その検索条件はどう指定するのか? 一般的にはパスによる指定とクエリによる指定がある。
パスは/user/1234などと指定し、クエリによる指定は?項目名=値などと指定する。
クエリとパスの使い分けだが、
- 参照したい情報が一意に決まるような場合はパスにし、
- 指定が省略可能である場合はクエリ
にするとよい。
また、クエリの場合
- 完全一致のニュアンスを取る場合は項目名=値の形式にし、
- 部分一致の場合はq=値
とするのがよい。
検索では結果が大量に返ることもあるので取得数と取得位置もクエリとして渡せるようにしておく必要がある(SQLでいうlimitとoffsetである)。
渡すクエリ名としては、limit/offsetとするかper_page/pageとするかでわかれるがAPI内では必ずどちらかに統一しておくこと。
なお、取得位置の指定としては相対位置と絶対位置の指定方法があるが、基準とするもの(idや日付など)以降のものとする絶対位置の方が望ましい。
3.2 自分自身を示すエンドポイント
認証を必要とするエンドポイントの場合、自分自身の情報を示すエンドポイントを用意しておくのが望ましい。自分自身を示すのは例えばself・meなどである。
理由としては二つある。まず一つ目は、自分自身の情報を取得するときidを渡すのは不適切であるからだ。二つ目は、self・meなど自分自身を示すエンドポイントを用意しておけば他ユーザへのアクセスの区別が容易につくからだ。
/users/1111 → id:1111というユーザ情報へのアクセス
/users/me → 自分自身の情報へのアクセス