usualoma
2/27/2016 - 1:45 AM

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

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

api.md
content_copyfile_download
  • Rendered
  • Source

基本は、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

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

同じ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, // 回答のリソースは含まない。回答の数は、場合によっては含んでもよい
}

エラー時のレスポンス

HTTP Verbs の扱い