ずっと前から気になっていて読もうと思っていた、Web API Design | Apigeeを読んでみました。全体的な感想としては、読んでよかった。これからAPIを作る際の基本的な方針になりそう。という感じです。「Web API: The Good Parts
」も以前読んでとても良いなと感じたのですが、こちらのほうがさらに本質的で筋肉質な印象を受けました。
気になったことのメモ
読みながら気になったことをメモしていたのですが、特にこれは自分のものにしたいというところを書き出していきます。
Rest狂信者ではなく実践的Rest利用者のために
冒頭で、Rest狂信者になることなく、実践的にRestを使う人のためのものという感じのことが書いてある。
There should be only 2 base URLs per resource.
例えばリソースに対して、baseとなるURLは以下の二つになるということです。また、関連してリソース名から動詞を排除しましょうということでした。
/dogs: a collection/dogs/1234: a specific element in the collection
Use HTTP verbs to operate on the collections and elements.
開発者はHTTPの動詞に慣れているから直感的にわかるし、いろんなことができるからHTTPの動詞で処理は決める。
Simplify associations – sweep complexity under the ‘?’
GET /owners/5678/dogs POST /owners/5678/dogs
こんな感じのインターフェイスにすると複雑性が増す。/resource/identifier/resource以上に深くはしない。ではどうするか？
GET /dogs?color=red&state=running&location=park
オプショナルな状態や属性をベースURLの?以降につけることで、シンプルに使えるようにする。
Use HTTP status codes
エラーを返すときには、HTTPのstatus codesを使いましょう。そして、たくさん使う必要はない。その代わり、errorにいろいろな情報を含めてあげましょう。errorが関連するドキュメントのURLを一緒に返してあげるのは良い方法。
APIとして使われているstatus codesの例:
Google GData
200 201 304 400 401 403 404 409 410 500
Netflix
200 201 304 400 401 403 404 412 500
Digg
200 400 401 403 404 410 500 503
以外と少ない。
あと、HTTPのstatus codesを返すのは普通かなと思っていたら、Facebookの場合は常に200を返して、responseのbodyでハンドルする仕組みになっているらしい…（今もそうかは知らないけれど）。
error message example
{"developerMessage" : "Verbose, plain language description of the problem for the app developer with hints about how to fix it.", "userMessage":"Pass this message on to the app user if needed.", "errorCode" : 12345, "more info": "http://dev.teachdogrest.com/errors/12345"}
Pagination and partial response
- Add optional fields in a comma-delimited list
- example: /dogs?fields=name,color,location
- Use limit and offset: /dogs?limit=25&offset=50
それぞれのレスポンスにレコードのtotal numberをmetadataとして含める。これはよくある。limitとoffsetのところ、良いと思うけど、timestampで要求するのもいいような気がする。Twitterはそれだった気がする。
What about responses that don’t involve resources?
リソースに関係ないresponseはどうする？verbsにしたりするらしい。例えば、
/convert?from=EUR&to=CNY&amount=100
What about attribute names?
JavaScriptの慣習に従うと良いらし。CamelCase。
Tips for search
リソースをまたいだ検索を提供したいときは、Google modelがいいらしい。
/search?q=fluffy+fur
Chatty APIs
これ、嫌な奴。一つの目的を達成したい（例えば、たぶん、shopの一覧と言い値をしているかどうかが欲しい）ときに、shopごとのいいね情報を個別でrequestしなきゃいけない時とかだと思う。
これには明確な解決法が示されている。これがとくに実践的Restぽい。
まずRestのAPIを完成させて、ショートカットを提供すること 先にショートカットを作ってはいけない。
The API Façade Pattern
詳細は、本文参照！
関連
