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)

Proposal

• 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の結果で分けるという手もある(配列か単数かで・・・)。

References

Sites

• Apigee Web API Design
• Web API: The Good Partsを読んだので「良いURI」についてまとめた
• 翻訳: WebAPI 設計のベストプラクティス
• GoogleのWebAPI設計とWebAPI設計のベストプラクティスを比較してみる
• APIを設計する前に読みたいガイドラインまとめ

Books

• Web API: The Good Parts