こんな API だったらいいなの案

api.md

基本は、JSON でリクエスト/レスポンス

• クライアントはリクエストヘッダで、 Accept: application/json と Content-Type: application/json を送る
  • リクエストボディも JSON
• サーバーはレスポンスヘッダで、Content-Type: application/json を送る

バージョン番号をパスに入れるか (/v1/questions とか)

• 入れなくて良い
  • 必要になったらリクエストヘッダで X-Api-Version: 1 するとか考える

200 以外のステータスになりうるものをどう返すか

「入力された値に不備があり、受け付けられなかった場合」など 422 Unprocessable Entity を返せるとよい。 ただ、HTTP のステータスコードとして 4xx を返すと、

• 本当にエラーが起きている
• 正常な結果だが 4xx

を区別できず、サーバーの運用上好ましくないかもしれない。

その点を考慮して、「サーバーのエラーではなく、APIの処理上のエラー」に関しては、 HTTP としては 200 を返し、 X-API-Status: 422 を返す、がよい気がする。

「そんな面倒なことしなくても 422 返してしまえばいい」という考え方もありだと思います。(あるいは、 JSON-RPC にしよう、とか)

リスト系の API からのレスポンス

[
  {
    "id": 1
  },
  {
    "id": 2
  },
]

のように、リソースのみを含むレスポンスがよい。以下のようにメタ情報は含まないようにしたい。

{
  "prevPage": 1,
  "nextPage": 3,
  "total": 100,
  "objects": [
    {
      "id": 1
    },
    {
      "id": 2
    },
  ]
}

メタ情報はレスポンスヘッダに入れる (どんな風に入れるかは検討。大きくないなら JSON で入れてもいいかもしれない) GitHub の API にインスパイアされています。

Link: <https://api.bitkids.com/resource?page=2>; rel="next", <https://api.bitkids.com/resource?page=5>; rel="last"
X-Object-Count: 100

メタ情報を積極的に入れるか

• http://magazine.rubyist.net/?0050-Hypermedia での、HAL や JSON-LD も入れるか
• そこまで複雑なものにはならないと思うので、シンプルなデータだけでよい

同じURLからのレスポンスはユーザー毎には変わらない (ユニーク)

• /questions/1 という URL があった時、どのユーザーが見てもレスポンスは同じ
  • 「見える/見えない」の違いはある

例えば以下のようなことはしない。

• クライアント1へのレスポンス

{
  "secret_column": "my secret data"
}

• クライアント2へのレスポンス

{
  "secret_column": null
}

関連するリソースは、関連先が1つ (1, 0..1) なら積極的に含む、複数なら含まない (, 1..)

{
  "student": {
    "name": "A Student",
  },
  "answers_count": 10, // 回答のリソースは含まない。回答の数は、場合によっては含んでもよい
}

エラー時のレスポンス

• GitHub の API の方針が良さそう https://developer.github.com/v3/#client-errors

HTTP Verbs の扱い

• (一般的なものだけど)GitHub の方針が良さそう https://developer.github.com/v3/#http-verbs