開発エンジニアのCHIHIRO.Hです。
前回の記事（vol1）ではWebAPIの基本概念について記載しました。
本記事ではWebAPIにおける「エンドポイント設計」について記載します。
WebAPIのエンドポイント設計は、データ取得や更新の効率化、セキュリティの強化、将来に向けた拡張性の確保、保守性の向上等を実現し、開発者や利用者が直感的に扱いやすいAPIを提供するために重要な役割を果たします。
URI設計の原則からエンドポイント設計、パスパラメータやクエリパラメータについてをご紹介します。
2. エンドポイント設計とは
エンドポイントとは、APIにアクセスするためのURI（Uniform Resource Identfiier）です。エンドポイントは、APIの「入り口」であり、特定の操作を行う場所を指定します。一般的にREST APIエンドポイントは以下のような形で構成されます。
http(s)://<ドメイン>/<リソース>/<リソースID>/<サブリソース>?<クエリパラメータ>
- ドメイン：APIのホスト名（例: example.com）。
- リソース：操作対象となるエンティティ（例: products、users）。
- リソースID：特定のリソースを識別するためのID（例: 123）。
- サブリソース：特定リソースに関連するサブエンティティ（例: /users/123/orders）。
- クエリパラメータ：リソースの絞り込みやソート、その他の追加オプションの指定（例: ?sort=asc&limit=10）。
2.1. URI設計の原則
URIの設計において重要な原則とは、「覚えやすく、どんな機能を持つURIなのかがひと目でわかる」ことです。具体的には以下のような点を考慮して設計します。
◆短くて入力しやすいURI
URIはできるだけ短く、ユーザーが簡単に入力できるものにするべきです。
良い例：
/products
悪い例：
/list-of-all-products-available-for-purchase
◆人間が読んで理解できるURI
URIを見るだけで、リソースや機能がわかるようにします。
良い例：
/users/123/orders
（ユーザーID123の注文を取得）
悪い例：
/getData?id=123&type=order
（何のデータかが不明確）
◆大文字小文字が混在していないURI
URIは一貫して小文字を使用することで、ミスを防ぎます。
良い例：
/products
悪い例：
/Products
◆サーバー側のアーキテクチャが反映されていないURI
URIに内部実装の詳細や技術を含めるのは避けるべきです。
良い例：
/users/123/profile
悪い例：
/cgi-bin/get_user_profile.php?id=123
（内部技術の露呈）
◆ルールが統一されたURI
URIの設計ルールを統一することで、予測しやすくなります。
良い例：
/products/567/reviews
（すべて名詞ベースでの一貫性）
悪い例：
/add_product_review?product_id=567
（名詞ベースと動詞ベースの混在）
2.2. APIのエンドポイント設計
APIのエンドポイントは、HTTPメソッドとURI設計を組み合わせて設計することになります。APIは一般的に「サーバー上に存在するリソースにアクセス／操作を行う」ためのものですので、Web APIを作成する中で最も多くかつ繰り返し設計する必要があります。そのことから設計する上で以下の点が特に注意すべきポイントになります。
- 名詞を使用する
- 適切な単語を使用する
- スペースやエンコードが必要となる文字は利用しない
- 単語をつなげる場合はハイフン（スパイナルケース）を利用する
2.3. APIパラメータ
APIにおけるリクエスト送信とは、「サーバー上に存在するリソースにアクセス／操作を行う」ためにサーバーに送信されるメッセージのことです。このときに利用できるパラメータには以下のようなものがあります。
① パスパラメータ
◆URLのパスに埋め込まれた変数のようなものです。
◆パラメータには、特定のリソースを識別するために必要な情報を入れます。
URL:https://example.com/products/{product_id}
② クエリパラメータ
◆URLの最後に追加する文字列になります。
◆URLの「?」以降に「key=value」形式で指定します。複数パラメータを追加する場合は&記号で繋げて指定します。
◆パラメータには、特定のリソースを識別するために必要な情報を入れます。
URL:https://example.com/products?category=books&page=1
③ ヘッダパラメータ
◆リクエストヘッダやレスポンスヘッダに含まれるパラメータです。
◆主に認証情報（Token）やContent-Typeのデータ形式を指定することに使用されます。
Authorization: Bearer token
Content-Type: application/json
④ ボディパラメータ
◆POSTメソッドなどのリクエストボディにデータを含めるパラメータです。
{
name: "Book",
price: "1000"
}
2.4. HTTPリクエスト
HTTPリクエストとは、クライアントからサーバーにデータを要求するために送信されるメッセージです。HTTPリクエストには以下のような特徴があります。
◆フォーマット形式はテキストベースとなる
GET /index.html HTTP/1.1
Host: example.com
◆HTTPメソッドで設定したい要求（GET、POST等）を指定する
POST /api/login HTTP/1.1
Host: example.com
Content-Type: application/json
{
name: "user1",
password: "password123"
}
◆ヘッダーに追加情報を設定できる
GET /api/data HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer <access-token>
◆リクエストボディの形式はJSONやXML、マルチパート等複数存在する
ー JSON形式
{
name: "user1",
age: "17"
}
ー XML形式
<user>
<name>user1</name>
<age>17</age>
</user>
ー マルチパート形式
POST /upload HTTP/1.1
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary
----WebKitFormBoundary
Content-Disposition: form-data; name="file"; filename="example.jpg"
Content-Type: image/jpeg
(binary data)
----WebKitFormBoundary--
◆リクエストボディには、追加や更新したい情報を入れる
<https://example.com/products/{product_id}>
// JSON形式の場合
{
name: "string",
description: "string"
}
リクエストを送信するとサーバーはそれに対応したHTTPレスポンスを返します。
まとめ
今回の記事ではWebAPIのエンドポイント設計についてをご紹介しました。Web API理解のために少しでもお役に立てれば幸いです。
次回の記事では、レスポンス設計についてご紹介します。
上記の記事に関してご質問ございましたら、お問い合わせください。