この記事では、API設計におけるエンドポイントとレスポンスの基本的な考え方をまとめます。短く、わかりやすく、そして統一感のあるAPIを設計するためのヒントを具体例とともに素人が本で学んだことを一部解説します。
エンドポイント設計
エンドポイント（APIにアクセスするためのURI）の設計は、APIの使いやすさを以下のルールを守ることで、直感的で保守性の高いAPIを作ることができます。
1 URIの基本設計
・短く入力しやすいURI
読んで字のごとくのことです。シンプルで覚えやすいことです。
意味が重複しないようにすることが大事
例
/users # ユーザー関連の操作
/tasks # ToDoリスト関連の操作
・人が読んで理解できるURI
これは省略した文字や日本語で書かないように世界共通の英単語を使うのがもっとも一般的ということ
利用する英単語でも「find」と「search」など似たような意味があったりするのできちんと調べて使い分けるようにする
メソッドで使い分けるとわかりやすい
例
POST /tasks # 新しいtaskを作成
GET /tasks # 全てのtaskを取得
PUT /tasks/{id} # taskを更新
DELETE /tasks/{id} # taskを削除
小文字で統一するために複数の単語が並ぶときはハイフン（ー）を使うスパイナルケース（ケバブケース）利用する
/to-do-items # 視認性が良い
もちろん既存のルールに統一するのがわかりやすい
・複数形を基本とする
例
/users # 良い例
/user # 一貫性がないため避ける
2.レスポンス設計
レスポンスではできるだけ短い単語を使い直感的に内容を理解できるように設計する
JSON形式と基本設計
APIレスポンスをJSON形式で記述することは、現代のWeb API設計において最も一般的な方法です。JSONはシンプルで軽量なデータ形式であり、データの構造が明確で、さまざまなプラットフォームで簡単に利用できるため、多くのメリットがあります。
・JSON形式とキャメルケース
JSON形式のレスポンスで複数の単語を扱う場合はキャメルケースを採用
例
{
"userId": 1,
"userName": "Taro Yamada",
"email": "taro.yamada@example.com"
}
複数のレスポンスがある場合は短いのがオブジェクトで包むことを
推奨していました。
例
{
"tasks": [
{
"id": 1,
"title": "買い物",
"isCompleted": false
},
{
"id": 2,
"title": "運動",
"isCompleted": true
}
]
}
ステータスコードの分類
レスポンス内容を理解しやすくする重要な要素
以下に主なステータスコードをカテゴリ別に整理して役割と使用例を示します
100番台 情報
200番台 成功
300番台 リダイレクト
400番台 クライアントサイドに起因するエラー
500番台 サーバサイドに起因するエラー
APIのことはまだ奥が深いですがとりあえず基本のみを書いていきました。
本にも書いてましたが作者が勧めている基本であって既存のルールに統一するのが一番だと思っています。