Web APIの基本構造とURL・認証まわりを整理してみた

Last updated at 2025-07-17Posted at 2025-07-17

1. はじめに

「Web APIって何となく使ってはいるけど、実はよくわかってない…」という状態を抜け出すため、Web APIの基本（URLの構造・設計、パラメータの扱い、認証など）を、自分なりに整理・復習する目的でまとめてみました。
同じようにAPIの構造に苦手意識のある方の参考にもなれば嬉しいです。

URLはプロトコル・ホスト・パスから成り立ちます。

もっと分解するとこんな感じ

URLには他にも、ポート・クエリ・フラグメントが含まれることがあります。
フラグメントはURLの末尾にある #〇〇の部分で、ページ内の特定の場所を示すものです。

URLはURIの一種。URNというものもある。

種類	説明	例
URI (Uniform Resource Identifier)	インターネット上のリソースを一意に識別するための総称。URLやURNを含む上位概念。	https://example.com/users/123 urn:isbn:978-4-00-000000-0
URL (Uniform Resource Locator)	リソースの「場所（アクセス方法と所在）」を示す識別子。実際にアクセス可能で、Web APIなどで主に使われる。	https://example.com/users/123
URN (Uniform Resource Name)	リソースの「名前」のみを示す識別子。場所は含まず、永続的かつ不変なIDとして扱われる。	urn:isbn:978-4-00-000000-0

APIでは、URLの中に値を埋め込む方法として「パスパラメータ」と「クエリパラメータ」があります。
パスパラメータはリソースの位置、クエリパラメータは取得条件として利用します。
/users/123/posts?sort=desc&page=2のように両方を組み合わせることも可能です。

比較項目	パスパラメータ	クエリパラメータ
書き方	`/users/123`	`/users?id=123`
使う場面	リソースを一意に識別	検索・絞り込み・ページングなど

ここまででURLの構造や各要素について整理しました。
では、実際にWeb APIを設計・利用するときは、どのようにURLを組み立てるべきか、というポイントをまとめてみました。

URLは一度公開すると変更が難しいため、なるべくシンプルで、変わりにくい構造にすることが重要です。

プログラミング言語や拡張子に依存しない
- 例：/users.json や /data.php のような形式は避ける。実装言語やデータ形式が変わったときに影響が出てしまうため
操作名（メソッド名を含めない）
- 例：/getUserInfo や /deleteUser のように、処理を表す動詞をURLに入れない。
  操作はHTTPメソッド（GET, POSTなど）で表現するのがREST的
セッションIDやAPIキーなど、セキュリティに関わる情報を含めない
- 例：/users/123?sessionid=abcd1234 のようなURLは、ログやブラウザ履歴に残ってしまうリスクがある
読みやすく、直感的に理解できるものにする
- 例：/users/123/posts のように、リソースと関係性が分かる構造が望ましい

APIには、アクセス制限のための「認証」が必要な場合があります。
ここでは基本的な「Basic認証」の仕組みと、具体的な使い方について学んだことをまとめます。

Basic認証は、ユーザー名とパスワードを組み合わせて認証する仕組みです。
以下のように、URLの中に認証情報を含める方法もありますが、パスワードがURLとして露出してしまうため非推奨。
https://user:password@api.example.com/users/123

パスワードをURLに含めず、リクエストヘッダーに Authorization を含めて、サーバーに送信するのが基本です。

# curlコマンドでの実行例

curl -u user:password https://api.example.com/users/123