Skip to content
This repository was archived by the owner on Apr 10, 2019. It is now read-only.

Good API Architecture

Jump to bottom
Takahiro Kubo edited this page Apr 10, 2017 · 5 revisions

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を叩かなくてよいようにする)。

  • Error Handling

    • HTTP status codesを使う(基本は、正常(200)・クライアント側の異常(400)・サーバー側の異常(500)の3種。認証は401)

References

Sites

Books

Clone this wiki locally