意味の分かるURLを設計したい

APIも画面も使う人のために設計するので、使う人が読みやすいものにしたいですね。

意味のあるリソース名を使用する

リソース名を具体的にしておくことで、API利用者は対象が何なのか直感的に理解できます。

良い例

このエンドポイントは「桜高校の2年3組の25番目の生徒」に関するリソースを明確に示しています。学校名、学年、クラス、生徒番号が具体的で、何が対象なのか一目で分かります。

/schools/sakura/grades/2/classes/3/students/25

悪い例

動詞「get」を使っており、リソースが何であるかが明確でありません。対象の学校や学年などもはっきりせず、理解が難しい構造です。

/getSchoolGradeClassStudent

階層構造を反映する

階層構造はリソースの関係性を直感的に示し、APIの読みやすさや操作性を高めます。階層がないと、リソースの関係性が分かりにくくなり、混乱を招きやすくなります。

良い例

このエンドポイントでは「桜高校」の「2年生」「3組」「25番目の生徒」というリソース間の親子関係が明確に階層構造で表現されています。利用者はリソースの関係性をすぐに理解できます。

/schools/sakura/grades/2/classes/3/students/25

悪い例

クエリパラメータを使用してリソースを表現しており、リソース間の親子関係が不明確です。階層的な依存関係が視覚的に表現されていないため、APIの理解が難しくなります。

/students?school=sakura&grade=2&class=3&student=25

動詞ではなくHTTPメソッドを使用する

RESTful APIの設計では、操作はHTTPメソッド（GET, POST, PUT, DELETEなど）で表現し、エンドポイント名にはリソースのみを使用することで、簡潔で理解しやすい設計ができます。

良い例

HTTPメソッド「GET」が生徒の情報取得を表し、エンドポイントはリソースに集中しています。エンドポイント名に動詞を使わないことで、シンプルかつわかりやすい構造になっています。

GET /schools/sakura/grades/2/classes/3/students/25

悪い例

エンドポイント名に「get」という動詞が含まれており、HTTPメソッドの「GET」と冗長になります。リソース名が不明確で、操作内容がエンドポイントに混ざっています。

/getStudentInfo

シンプルなパラメータを使用する

パラメータはシンプルで、必要な情報のみを短く記述することで、エンドポイントの可読性とメンテナンス性が向上します。複雑なクエリパラメータは理解しづらく、エラーの元となります。

良い例

メインのリソースは階層構造で示され、追加のフィルタリング情報（例えば生徒のステータス）はクエリパラメータでシンプルに指定されています。

/schools/sakura/grades/2/classes/3/students/25?status=active

悪い例

複数のクエリパラメータでリソースを指定しており、複雑で読みにくい設計です。リソースの階層関係も明確でなく、クライアントに負担がかかります。

/students?id=25&school_name=sakura&class_year=2&class_name=3&status=active

一貫性を保つ

一貫性のある命名と構造を保つことで、APIを使う際の学習コストを削減し、予測可能な設計が可能になります。ルールが一貫していないと、混乱を招き、保守もしにくくなります。

良い例

「学校」「学年」「クラス」「生徒」や「教師」というリソースが一貫して階層構造を使い、同じ命名パターンで統一されています。これにより、エンドポイントの予測が容易です。

/schools/sakura/grades/2/classes/3/students/25
/schools/sakura/grades/2/classes/3/teachers/5

悪い例

命名規則がバラバラで、リソースの表現方法に一貫性がありません。利用者は新しいエンドポイントを理解する際、毎回新しいパターンを学ぶ必要があり、学習コストが増えます。

/schools/sakura/classes/grade-2-3/students/25
/teachers-of-class-3/sakura/grade-2/teacher-5