Web API Designを読んだ

Web API Designを読んだずっと前から気になっていて読もうと思っていた、Web API Design | Apigeeを読んでみました。全体的な感想としては、読んでよかった。これからAPIを作る際の基本的な方針になりそう。という感じです。「Web API: The Good Parts」も以前読んでとても良いなと感じたのですが、こちらのほうがさらに本質的で筋肉質な印象を受けました。

Web API Design | Apigee

気になったことのメモ

読みながら気になったことをメモしていたのですが、特にこれは自分のものにしたいというところを書き出していきます。

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.

Ebook 2013 03 wad pdf

開発者は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

Ebook 2013 03 wad pdf

詳細は、本文参照!

関連

Pocket
LINEで送る

You may also like...