Good API Architecture

Practice

Principle

SSLでアクセスせよ
必ずバージョンを伴うようにする(URLに含めるのがお勧め(/v1/dogsなど))
JSONでの受け取り/返しが基本
Attribute名はCamelCaseにする(JavaScriptがCamelCaseなので、それに合わせる。 myObject.createdAtなど)
認証はOAuth 2.0

Architecture

Resource
- リソースの名前は具体的にする(itemsやassetsは避ける)
- URIは名詞(複数形)を利用し、動詞はメソッド(GET/POST/PUT/DELETE)で表現する
- リソースに対し2つのURIを用意する(collection, element = dogs, dogs/1234)
- 関連オブジェクトは一段階まで(/resource/identifier/resource)
- レスポンスに含めるフィールドを絞れるようにすべし(/dogs?fields=name,color,location)
- 件数を絞れるようにすべし(/dogs?limit=25&offset=50)。なお、この際全件数などの情報を含めた方が良い。
- 追加、変更時は変更後のオブジェクトを返す(別途GETを打たなくてよいようにする)
- 関連データを取れる手段を提供する(再度APIを叩かなくてよいようにする)。
- リソースでなく機能の場合(翻訳する、など)は動詞を利用し、名詞で表現するリソースと明確に区別する(/convert?from=EUR&to=CNY&amount=100など)
Error Handling
- HTTP status codesを使う(基本は、正常(200)・クライアント側の異常(400)・サーバー側の異常(500)の3種。認証は401)

Root: api.chakki.com/maccha/v0.1 (.comか?という話はあるが)
API
- path: /compare
- method: POST
- request parameter: {"source":"hogehoge", "target":"hugahuga"}
- response: {"similarity": 0.4}
Error
- 200: return response
- 400: {"type": "MissingParameter", "message":"source text is missing."} (例外のクラス=type、メッセージ=message)
- 500: {"type": "ParseError", "message":"can not parse the sentence"}

Discussion

複数POSTへの対応
- 1:N -> ある一文と、その他大勢の文のsimilarityを比較する
- N pairs -> [A, B], [C, D]といった多くのペアの一括判定を可能にする
- JSON parseの結果で分けるという手もある(配列か単数かで・・・)。

Sites

Books