参考になった点のまとめです。
HATEOAS
HATEOAS(hypermedia as the engine of application state)はAPIの返すデータの中に、次に行う行動、取得するデータ等のURIをリンクとして含めることで、そのデータを見れば次にどのエンドポイントにアクセスをすればよいかわかるような設計
例えば、
"link" : {
"url" : "http://nexturl",
"rel" : "next"
}
という風にAPIでクライアントの行動を制御する設計方針のことです。
メリット
- クライアントがあらかじめURIを知る必要が無いためサーバサイドで制御できる。
- URIをhackableにしなくてもよくなる。＞アクセス先を人間が見ても理解できなくすることで、セキュリティを高める
特定のクライアントのみで使われるAPIでは採用も考えれるかと思います。
HTTPメソッドを使った設計
下記、HTTPメソッドを正しく使ってAPIを設計するのがよいです。
- GET (READ)
- POST (CREATE)
- PUT (UPDATE)
- PATCH (UPDATE)
- DELETE (DELETE)
PUT/PATCHの使い分け
PUTはコンテンツ全体の更新に用います。それに対してPATCHはコンテンツ一部の更新に用います。
ステータスコードでエラーを表現する
| ステータスコード | 意味 |
|---|---|
| 100番台 | 情報 |
| 200番台 | 成功 |
| 300番台 | リダイレクト |
| 400番台 | クライアントサイドに起因するエラー |
| 500番台 | サーバサイドに起因するエラー |
エラーの場合は単にエラー情報をレスポンスボディの返すだけでなく、
クライアントからのリクエストが成功した場合のみ200番台を返す必要があります。
また、できるだけ下記ステータスコードの意味に近づけるように結果を返すようにします。
| ステータスコード | 名前 | 意味 |
|---|---|---|
| 200 | ok | リクエストは成功した |
| 201 | Created | リクエストが成功し、新しいリソースが作られた |
| 202 | Accepted | リクエストは成功した |
| 204 | No Content | コンテンツなし |
| 300 | Multiple Choices | 複数のリソースが存在する |
| 301 | Moved Permanently | リソースは恒久的に移動した |
| 302 | Found | リクエストしたリソースは一時的に移動している |
| 303 | See Other | 他を参照 |
| 304 | Not Modified | 前回から更新されていない |
| 307 | Temporary Redirect | リクエスしたリソースは一時的に移動している |
| 400 | Bad Request | リクエストが正しくない |
| 401 | Unauthorized | 承認が必要 |
| 403 | Forbidden | アクセスが禁止されている |
| 404 | Not Found | 指定したリソースが見つからない |
| 405 | Method Not Allowed | 指定されたメソッドは使うことが出来ない |
| 406 | Not Acceptable | Accept関連のヘッダに受理できない内容が含まれている |
| 408 | Request Timeout | リクエストが時間以内に完了しなかった |
| 409 | Conflict | リソースが矛盾した |
| 410 | Gone | 指定したリソースは消滅した |
| 413 | Request Entity Too Large | リクエストボディが大きすぎる |
| 414 | Reqeust-URI Too Long | リクエストされたURIが長すぎる |
| 415 | Unsupported Media Type | サポートしていないメディアタイプが指定された |
| 429 | Too Many Requests | リクエスト回数が多すぎる |
| 500 | Internal Server Error | サーバ側でエラーが発生した |
| 503 | Service Unavailable | サーバが一時的に停止している |
バージョン情報をURIに加える
http://api.yayoc.com/v1/friends
みたいな感じでバージョン情報はURIに加えたほうがよいです。
エンドポイントはひと目で理解できるように
複数形を用いる
複数形、単数形が混在すると煩雑になってしまい、混乱するので複数形を用いるほうがベターです。ただし、単語によっては単数形と複数形が同語の場合もあるため、考慮する必要があります。
よくない例) api.yayoc.com/v1/friend/1
よい例) api.yayoc.com/v1/friends/1
極力動詞は使わない
REST APIの基本はエンドポイントに動詞を使わず名詞のみで表したほうがシンプルになり理解しやすいです。
よくない例) api.yayoc.com/v1/get/friends/
よい例) api.yayoc.com/v1/friends/
英単語の選定は慎重に
英語がネイティブでない場合、適切な単語を選ぶのは難しいです。
ProgrammableWeb等を利用して適切な単語を選定しましょう。
まとめ
RESTfulなAPIを設計するためにはひとまず、
- HTTPの仕様の理解
- 理解しやすいエンドポイントの設定
が大事かなと思います。
既に、公開されているAPI(先人の知恵)を参考にシンプルに互換性のある設計を心がけていきたいです。