良いURI設計とは(エンドポイントの基本的な設計)#1
初めに
今回の記事は、WebAPIにおける良いURI設計についてまとめていきたいと思います。まず、良いURIの設計とは、一言で言うと、覚えやすく、どんな機能をもつURIなのかが一目でわかるということです。良いURI設計のポイントにおいて以下についてまとめていきたいと思います。
- 「覚えやすく、どんな機能をもつURIなのかが一目でわかる」とは？
- 短く入力しやすいURI
- 人間が読んで理解できるURI
- 大文字小文字が混在していないURI
- 改造しやすいURI
- サーバー側のアーキテクチャが反映されていないURI
- ルールが統一されたURI
「覚えやすく、どんな機能をもつURIなのかが一目でわかる」とは？
これは可読性と直感性に繋がっていきます。URIを見ただけで、それが何のリソースを指し、どのような情報を取得できるのかが想像できると、APIの使いやすさは格段に向上します。例えば、/productsとあれば「製品一覧」とすぐに理解できます。URIにおけるリソース名は、基本的に複数形を使用するのが一般的です。これは、URIが「リソースの集合」を表しているためです。たとえば、ユーザー一覧を取得するAPIであれば、/users と記述するのが自然です。
短く入力しやすいURI
これも可読性と直感性、そしてユーザビリティに大きく関わります。URIが冗長だと、タイピングミスが増えたり、どこまでが同じリソースを示すのかが分かりにくくなったりします。シンプルで短いURIは、理解しやすく、覚えやすいです。
人間が読んで理解できるURI
「ヒューマンリーダブル」とも言われますが、URIに意味のある単語やフレーズを用いることで、開発者がURIの意図を容易に把握できます。例えば、IDのみの羅列ではなく、/users/123/profileのように間に意味のある単語が入ることで、より理解しやすくなります。
大文字小文字が混在していないURI
これは一貫性と堅牢性のために非常に重要で、URIは大文字・小文字を区別する場合があるため、混在していると意図せず異なるリソースとして扱われたり、入力ミスを誘発したりします。一般的にはすべて小文字で統一し、単語の区切りにはハイフン（-）を使用するのがベストプラクティスです。
単語をつなげる場合のルール
単語の区切りには 「ハイフン（-）」 を使用する。
- 良い例:
- /user-profiles (ユーザープロフィール)
- /product-categories (製品カテゴリ)
- /order-items (注文品目)
改造しやすいURI
これは拡張性や柔軟性に繋がります。例えば、/products/123というURIがあったとして、その製品のレビューを見たい場合に/products/123/reviewsのように末尾に情報を追加することで、新たなURIを容易に作成できるような設計が良いとされます。これはURIの階層構造を意識することでも実現できます。
サーバー側のアーキテクチャが反映されていないURI
これはセキュリティと疎結合性の観点から非常に重要です。URIに.phpや.jsp、cgi-binといった拡張子やディレクトリ構造、フレームワーク名などを含めると、内部構造が推測されやすくなり、攻撃のリスクを高める可能性があります。また、将来的にサーバー側の技術スタックが変更された際に、URIも変更する必要が生じてしまうため、保守性が低下します。URIはあくまで「リソースの識別子」であり、その実装方法を示すべきではありません。
ルールが統一されたURI
API全体でURIの命名規則や構造が統一されていると、API利用者は新しいURIに出会った際にも、そのパターンから動作を予測しやすくなります。
まとめ
良いURI設計は、APIの使いやすさ・保守性・拡張性を大きく左右します。以下に簡単に要点をまとめます。
- URIは「覚えやすく、見ただけで意味が分かる」ようにする
- シンプルで短く、ヒューマンリーダブルな表現を心がける
- 大文字小文字の混在を避け、小文字とハイフンで統一する
- URIは階層構造を意識し、拡張しやすく設計する
- サーバーの内部構造や技術要素をURIに含めない
- 一貫性ある命名・設計ルールをAPI全体で統一する
第二弾目はこちらになります。
Discussion