Web、モバイルアプリ開発においてAPI設計は重要な要素である一方で経験をしないことにはなかなか自信を持って設計することが難しい。
ここで筆者が主張したいことはAPI設計は構造的に捉えることで設計をできるようになってほしいということである。
構造的に捉えることで、API設計の理解が深まり、設計の変更に対しても柔軟に対応できる。
ここからは設計のお題を提示し、構造的に捉えることで設計する練習をしていく。
お題
SNSアプリを作っていてコメントを投稿する機能と一覧表示する機能があるとする。
このとき、コメントを修正する機能を追加することになった。
以下の要求を満たすAPIを設計せよ。
- コメントを修正できること
- 特定のユーザーじゃないと更新させないこと
- コメントの文字数制限を適切に設定
このお題に対してどのようにするかを考えてみてください。
ここから下には筆者の考え方の一例を示す。
考え方
REST APIを考えるにおいて、HTTPの構造を理解しておくことが重要である。
HTTPはリクエストとレスポンスの構造になっている。
リクエスト
リクエストには
- リクエスト行
- ヘッダー
- ボディ
で構成される。
リクエスト行は
- メソッド（GET, POST, PUT）
- URI（Path）
- バージョン
ヘッダー/ボディは各keyとvalueで構成される。
レスポンス
レスポンスには
- ステータス行
- ヘッダー
- ボディ
で構成される。
ステータス行は
- ステータスコード（200, 400, 500）
- メッセージ
ヘッダー/ボディは各keyとvalueで構成される。
お題に対する設計
各要求に対してどこにどのような情報を持たせるかを考える。
- コメントを修正できること -> リクエストボディに修正内容を持たせる
- 特定のユーザーじゃないと更新させないこと -> ヘッダーに認証情報を持たせる（サーバーサイドでユーザーを判定する）
設計
ここから設計がどうなるかを書く。
リクエスト
- メソッド: Put
- URI: /api/v1/posts/{post_id}
- ヘッダー: Authorization: token
- ボディ: {コメントの修正内容}
レスポンス
レスポンスには正常系だけでなくエラー系も考える。
- 200（正常系）
- bodyは特になし
- 400（クライアントエラー）
- エラーの原因: ユーザーが不正
- エラーの原因: 文字数が多い
- 401（認証エラー）
- エラーの原因: 認証情報がない
- 403（権限エラー）
- エラーの原因: 権限がない
- 404（リソースが見つからない）
- エラーの原因: リソースが見つからない
- 429（リクエストが多すぎる）
- エラーメッセージ: too many request
- 500（サーバーエラー）
- エラーメッセージ: internal server error
まとめ
今回は簡単なお題と簡単な回答例を記載した。
構造的にHTTPを捉えてどの情報を何処に持たせるかを考えてAPI設計をすることで、柔軟に対応できるようになりましょう。