Web APIのドキュメントに明示する必要がある項目としては、次のような事柄が挙げられます。
- 認可(Authorization)の方法、必要な権限(scope)
- エンドポイントURLやHTTPメソッド
- リクエスト形式
- レスポンス形式
- エラー表現
- 説明やサンプル
エラー表現
主要なHTTPステータスコード
- 2xx系(成功)
- 3xx系(リダイレクト)
- 4xx系(クライアント側のエラー)
- 5xx系(サーバ側のエラー)
以下、本記事の著者が使っているステータスコードの使用例です。
2xx系
200 OK
- エントリリソースの取得(GET)
- コレクションリソースの取得(GET
- エントリリソースを更新し、現在のリソースを返す(PUT, PATCH)
- オーバーロードPOST/GETを行い、レスポンスボディを返す(POST, GET)
201 Created
- エントリリソースの作成(POST)
202 Accepted
- 非同期処理全般(POST, PUT, DELETE, PATCH)
204 No Content
- エントリリソースを更新するが、現在のリソースは返さない(PUT, PATCH)
4xx系
400 Bad Request
クライアント側の汎用エラー
401 Unauthorized
クライアントが適切なAuthorizationヘッダを送ってこなかった場合
403 Forbidden
リクエスト形式も認可情報も妥当であるが、そのほかの何らかの理由によりアクセスが拒否された場合
409 Conflict
リソースの変更が不可能又は矛盾している
429 Too Many Requests
リクエストの回数制限などにひっかかる場合に用いる
エラー表現と標準仕様
HTTPエラー表現のRFCとしてhttp-problemというものがあります。
ドキュメントに図を活用する
PlantUMLというUMLモデリングツールについて紹介されています。UMLについてはあまり詳しくないので省略で…。
感想
RESTの基本の整理のように、初心者にも役に立つ部分がありますが、基本的には、「Web APIの設計のベストプラクティスを知りたい」という読者に最もフィットする記事だと思います。クローズドなAPIであれば、多少いい加減な設計でも、クライアント側との合意ができていれば問題ありません。しかし、多くのユーザーに提供するAPIの場合、設計が非常に重要になります。
RFCのようなパブリックな仕様に基づいたAPI設計や、JSON Schemaを使用したマシンリーダブルな仕様書の作成等、意識すべきポイントの勘所がおさえられていて参考になる記事でした。