はじめに
REST APIの設計において、URI（Uniform Resource Identifier）の設計は非常に重要です。良いURI設計は、APIの使いやすさやメンテナンスの容易さに大きく影響します。この記事では、REST APIのURI設計における9つのポイントを具体例と共に解説します。
URI設計のポイント
1. 短く入力しやすい（冗長なパスを含まない）
URIはできるだけ短くし、入力が簡単であることが重要です。冗長なパスを含まないようにしましょう。
例
- 良い例:
/users - 悪い例:
/api/v1/users/list/all
2. 人間が読んで理解できる（省略しない）
URIは人間が読んで理解できるように設計する必要があります。省略を避け、明確な名前を使用しましょう。
例
- 良い例:
/users - 悪い例:
/usr
3. 大文字小文字が混雑していない（すべて小文字）
URIはすべて
小文字で記述することで、一貫性を保ち、誤解や入力ミスを防ぎます。
例
- 良い例:
/users - 悪い例:
/Usersまたは/UsersList
4. 単語はハイフンでつなげる
単語をつなぐ際にはハイフン（-）を使用することで、URIが読みやすくなります。アンダースコア（_）は避けましょう。
例
- 良い例:
/user-profiles - 悪い例:
/user_profilesまたは/userProfiles
5. 単語は複数形を利用する
リソースのコレクションを示す場合、単語を複数形で表現するのが一般的です。
例
- 良い例:
/users - 悪い例:
/user
6. エンコードを必要とする文字を使わない
URIには、空白や特殊文字を避け、エンコードが必要な文字を使わないようにしましょう。
例
- 良い例:
/users - 悪い例:
/users list
7. サーバー側のアーキテクチャが反映されていない
URIは、サーバーの内部構造やアーキテクチャを反映させず、リソースの識別に集中するべきです。
例
- 良い例:
/users - 悪い例:
/database/users
8. 改造しやすい（Hackable）
URIは直感的に変更できる（改造しやすい）ことが理想です。例えば、ユーザーの投稿を参照する際に、ベースURIから自然に推測できるようにしましょう。
例
- 良い例:
/users/123/posts（ユーザーID 123の投稿） - 悪い例:
/posts?user_id=123
9. ルールが統一されている
URIの設計には一貫したルールを適用することで、使いやすさとメンテナンス性が向上します。
例
- 良い例: 全てのリソースURIが同じパターンに従う
/users/users/123/users/123/posts
- 悪い例: URIのパターンがバラバラ
/users/user_detail/123/post/list?user_id=123
具体例
以下に、上記のポイントを踏まえた具体的なURI設計例を示します：
-
ユーザーリソースの操作
- ユーザーの一覧取得:
GET /users - 新しいユーザーの作成:
POST /users - 特定ユーザーの取得:
GET /users/123 - ユーザー情報の更新:
PUT /users/123 - ユーザーの削除:
DELETE /users/123
- ユーザーの一覧取得:
-
ユーザーの投稿リソースの操作
- 特定ユーザーの投稿一覧取得:
GET /users/123/posts - 特定ユーザーの新しい投稿作成:
POST /users/123/posts - 特定の投稿の取得:
GET /users/123/posts/456 - 投稿の更新:
PUT /users/123/posts/456 - 投稿の削除:
DELETE /users/123/posts/456
- 特定ユーザーの投稿一覧取得:
まとめ
良いURI設計は、APIの使いやすさとメンテナンス性を大きく向上させます。ここで紹介した9つのポイントを参考にして、わかりやすく、一貫性のあるURIを設計しましょう。具体例を参考にしながら、自分のプロジェクトに最適なURIを考えることで、開発効率を向上させることができます。