以前、REST APIの基本を記事にしました。API の資料を読んでいると、そのあとすぐに出てくるのが「エンドポイント」という言葉です。この記事では、Microsoft Graph・Azure・GitHub の公式ドキュメントで確かめながら、エンドポイントの URL の読み方と、バージョンや環境の違いが URL のどこに表れるかを図にしました。
- APIエンドポイントが何を指す言葉か
- エンドポイントの URL の読み方と、バージョン・環境の表し方
- 公開用と社内用の違いと、エンドポイントを扱うときの注意点
APIエンドポイントとは
APIエンドポイントは、プログラムが API を呼び出すときに、リクエストを送る先の URL です。役所にたとえると、建物の住所がサービス全体の入口にあたり、その中に「住民票」「税金」のような窓口が並んでいる、というイメージです。
この言葉は、資料によって指す範囲が少し違います。Microsoft Graph の資料では、https://graph.microsoft.com を「Microsoft Graph API のエンドポイント」と呼んでいます。一方で、/users や /groups のように、操作ごとの URL を1つずつ「エンドポイント」と数える資料も多くあります。
| 呼び方 | 指す範囲 | 例（Microsoft Graph） |
|---|---|---|
| サービスのエンドポイント | サービス全体の入口 | https://graph.microsoft.com |
| ベースURL | 入口にバージョンまでを足したもの。SDK の設定などで使う | https://graph.microsoft.com/v1.0 |
| 個々のエンドポイント | 1つひとつの操作の URL | https://graph.microsoft.com/v1.0/users |
資料を読むときは、どちらの意味で使っているかを前後の文から判断します。この記事では、区別が必要なところは「ベースURL」と「個々のエンドポイント」と書き分けます。
同じURLでも、メソッドが違えば別の操作
個々のエンドポイントは、URL だけでなく HTTP メソッドと組み合わせて1つの操作になります。Microsoft Graph では、同じ /users に GET を送るとユーザーの一覧が返り、POST を送ると新しいユーザーを作ります。
例：Microsoft Graph のユーザー操作（公式ドキュメントのリクエスト例）
GET https://graph.microsoft.com/v1.0/users POST https://graph.microsoft.com/v1.0/users
API の仕様を書くための形式である OpenAPI でも、パスごとに get や post といった操作を並べて書きます。API の資料で「GET /users」のようにメソッドとパスを並べて書いてあるのは、この組み合わせで1つの操作を表しているからです。HTTP メソッドそのものは、REST APIの記事で説明しています。
エンドポイントのURLを部品に分けて読む
エンドポイントの URL は、部品に分けると読みやすくなります。URL の部品の分け方は RFC 3986 で決められていて、API の URL もこの形に従っています。
| 部品 | 例 | 意味 |
|---|---|---|
| スキーム | https | 通信のしかた。API はほとんどが HTTPS で呼ぶ |
| ホスト | graph.microsoft.com | API を受け付けるサーバの名前。DNS で IP アドレスに変換される |
| ポート | （省略） | https の既定は 443 番。既定のときは書かない |
| バージョン | /v1.0 | API の版。パスに入れる API と、別の場所に書く API がある |
| パス | /users/{id} | 操作する対象（リソース）。{id} には実際の ID を入れる |
| クエリ | ?$select=mail | 条件やオプション。? のあとに 名前=値 を & でつなぐ |
| フラグメント | #… | ブラウザの側だけで使う部分で、サーバには送られない |
パスパラメータとクエリパラメータ
パスの中の {id} のように波かっこで囲まれた部分を、パスパラメータといいます。資料に {id} と書かれていても、送るときは波かっこごと実際の値に置き換えます。クエリパラメータは ? のあとに付ける 名前=値 の組で、結果の絞り込みや、返す項目の指定によく使います。
OpenAPI では、パラメータの置き場所として path（パス）、query（クエリ）、header（ヘッダ）、cookie（Cookie）の4つが決められています。URL には見えないヘッダも、エンドポイントに情報を渡す置き場所の1つです。
RFC 3986 では、スキームとホストは大文字と小文字を区別せず、パスやクエリなどほかの部品は、スキームに別の決まりがない限り区別するものとして扱います。実際の扱いは API ごとに違い、Microsoft Graph はリソース名やクエリパラメータの大文字小文字を区別しない一方で、ID などの値は区別します。資料に書かれたとおりの綴りで送るのが確実です。
バージョンはどこに書くか
API は、機能を足したり直したりしながら使われ続けます。項目の名前を変えたり必須のパラメータを増やしたりすると、それまで動いていたプログラムが動かなくなります。そこで、こうした変更は新しいバージョンにまとめて出し、古いバージョンもしばらく残します。GitHub は、互換性を壊す変更は新しいバージョンで出すと説明しています。
バージョンを書く場所は、API によって主に次の3つに分かれます。
パスに書く（Microsoft Graph）
Microsoft Graph は、ホストのすぐ後ろに v1.0 か beta を書きます。beta はプレビュー中の API で、予告なく変わることがあるため、Microsoft は本番のシステムで beta に頼らないよう案内しています。
例：Microsoft Graph（公式ドキュメントのリクエスト例）
GET https://graph.microsoft.com/v1.0/me/ GET https://graph.microsoft.com/beta/me/
クエリに書く（Azure Resource Manager）
Azure のリソースを操作する Azure Resource Manager の REST API は、https://management.azure.com/ を使い、リクエストに api-version というクエリパラメータを付けます。値は 2021-04-01 のような日付の形です。
例：リソースグループ内のリソースの一覧（公式ドキュメントのリクエスト例）
GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/resources?api-version=2021-04-01 HTTP/1.1
Authorization: Bearer <bearer-token>
Host: management.azure.com
この例は、HTTP のリクエストをそのまま書いた形です。1行目にはパスとクエリだけが入り、ホストは Host ヘッダに入ります。ブラウザのアドレス欄に入れる URL とは見え方が違いますが、ホストとパスをつなげると同じ URL になります。
ヘッダに書く（GitHub）
GitHub の REST API は、URL にはバージョンを入れず、X-GitHub-Api-Version というヘッダで指定します。このヘッダを付けないと 2022-11-28 版として扱われ、サポートが終わったバージョンを指定すると 410 Gone が返ります。
例：GitHub の REST API（公式ドキュメントの例）
curl --header "X-GitHub-Api-Version:2026-03-10" https://api.github.com/zen
GitHub の資料では、最新のバージョンは 2026-03-10、2022-11-28 のサポート終了日は2028年3月10日と書かれています。サポート中のバージョンは変わっていくので、使う前に資料で確かめてください。
書き場所ごとの違い
| 書き場所 | 例 | 特徴 |
|---|---|---|
| パス | /v1.0/users | URL を見ればバージョンがわかる。版が変わると URL も変わる |
| クエリ | ?api-version=… | パスは同じまま、リクエストごとに版を選ぶ |
| ヘッダ | X-GitHub-Api-Version | URL は変わらない。URL だけを見ても版はわからない |
環境ごとにエンドポイントを分ける
同じ API でも、開発・検証・本番で接続先を分けるのが一般的です。OpenAPI の仕様書にも、servers の欄に開発用・検証用・本番用の URL を並べて書く例が載っています。パスはどれも同じで、違うのはベースURLです。
プログラムの中に URL を直接書くと、環境を変えるたびに書き換えが必要になり、検証のつもりで本番を呼んでしまう事故にもつながります。ベースURLは設定ファイルや環境変数に置き、環境ごとに値を変えるのが基本です。
クラウドの種類でエンドポイントが変わる例
Microsoft のクラウドには、世界共通のサービスとは別に、米国政府向けや中国向けの「国内クラウド」があります。Microsoft Graph のエンドポイントも、クラウドごとに違うホスト名になっています。
| クラウド | Microsoft Graph | サインイン（Microsoft Entra ID） |
|---|---|---|
| 世界共通 | https://graph. | https://login. |
| 米国政府（GCC High） | https://graph. | https://login. |
| 米国政府（DoD） | https://dod-graph. | https://login. |
| 中国（21Vianet） | https://microsoftgraph. | https://login. |
国内クラウド向けに取ったアクセストークンは、世界共通のサービスやほかのクラウドでは使えません。API のホストだけを変えても、トークンを取る先（サインインのエンドポイント）がそろっていなければ認証に失敗します。なお、米国政府向けでも GCC の環境は世界共通のエンドポイントを使います。
公開用のエンドポイントと社内用のエンドポイント
エンドポイントには、インターネットから届く「公開エンドポイント」と、社内ネットワークやクラウドの仮想ネットワークの中からだけ届くものがあります。インターネットに公開する API の前には、リバースプロキシなどを置いて入口を1か所にまとめることが多く、その構成はフォワードプロキシとリバースプロキシの記事で説明しています。
Azure のプライベートエンドポイントは、仮想ネットワークのプライベート IP アドレスを持つネットワークインターフェースです。Azure Storage などのサービスに、仮想ネットワークの中からプライベート IP でつなぐために使います。サービスを仮想ネットワークの中に持ってくるイメージです。
プライベートエンドポイントでは DNS の設定が大事です。サービスの名前（FQDN）が、仮想ネットワークの中ではプライベート IP に解決されるように、プライベート DNS ゾーンなどで設定します。
プライベートエンドポイントを作っただけでは、公開側の入口は閉じません。Microsoft の資料でも、プライベートエンドポイントはプライベート IP の入口を足すもので、パブリックネットワークからのアクセスを必ず制限するわけではないと説明しています。社内からだけ使わせたい場合は、サービス側で公開アクセスを無効にする設定も合わせて行います。
「エンドポイント」と呼ばれるほかのもの
IT の世界では、「エンドポイント」がほかの意味でも使われます。同じ言葉でも、何を指しているかは文脈で変わります。
| 言葉 | 指すもの | 例 |
|---|---|---|
| APIエンドポイント | API を呼び出す URL | https://graph. |
| サインインの エンドポイント | サインインやトークンの発行を受け付ける URL。API と同じく URL を指す | https://login. |
| エンドポイント （端末） | ネットワークの端にある PC やサーバ、スマートフォン。EDR の「E」はこの意味 | EDR の記事 |
| プライベート エンドポイント | Azure の仮想ネットワークに置く、サービス用のネットワークインターフェース | 図5 |
エンドポイントを扱うときの注意点
HTTPS で呼ぶ
API の通信には、認証のための情報や業務のデータが乗ります。Azure の REST API の資料でも、リクエストの URL には HTTPS を使うよう求めています。http:// で始まるエンドポイントは、そのまま使わずに確かめます。
秘密の値を URL に入れない
URL は、ブラウザの履歴や、Web サーバ・プロキシのログなど、いろいろな場所に記録されます。OAuth のアクセストークンの送り方を決めた RFC 6750 も、トークンを URL のクエリに入れる方法はログに残りやすいため、ほかの方法が使えない場合を除いて使うべきではないとしています。トークンや API キーは、Authorization などのヘッダで送ります。
| 送り方 | 例 |
|---|---|
| 避ける | GET /resource?access_token=… |
| 使う | Authorization: Bearer … |
使っているエンドポイントとバージョンを一覧にしておく
バージョンにはサポート期限があり、期限を過ぎたバージョンは使えなくなります。どのシステムがどのエンドポイントのどのバージョンを呼んでいるかを一覧にしておけば、期限の前に移行の計画を立てられます。
API を提供する側も同じです。古いバージョンや検証用のエンドポイントを公開したままにすると、管理の目が届かない入口が残ります。OpenAPI で仕様書を書いておくと、servers と paths に入口の一覧がまとまるので、棚卸しの土台になります。
うまくいかないとき
| 起きていること | よくある原因 | 確認すること |
|---|---|---|
| 404 Not Found | パスのつづり違い、存在しない ID | 資料のパスと1文字ずつ見比べる |
| Azure の API が エラーを返す | api-version の付け忘れ、そのリソースで使えない値 | 資料に載っている api-version の値を付ける |
| 410 Gone （GitHub） | サポートが終わったバージョンを指定した | X-GitHub-Api-Version をサポート中の値にする |
| 認証に失敗する | トークンを取ったクラウドと、呼んでいるエンドポイントのクラウドが違う | サインインと API のエンドポイントの組み合わせ |
| 社内から公開側に つながる | 社内の DNS がプライベート IP を返していない | 社内で nslookup し、サービス名がプライベート IP になるか |
まとめ
| 項目 | ポイント |
|---|---|
| APIエンドポイント | API にリクエストを送る先の URL。サービスの入口を指すことも、個々の操作の URL を指すこともある |
| URLの部品 | スキーム・ホスト・（ポート）・パス・クエリ。パスで対象を、クエリで条件を指定する |
| 操作 | メソッドとパスの組み合わせで1つの操作になる（GET /users と POST /users は別の操作） |
| バージョン | パス・クエリ・ヘッダのどこに書くかは API ごとに違う |
| 環境 | 開発・検証・本番や、クラウドの種類でベースURLが変わる |
| 公開と社内 | プライベートエンドポイントは DNS とセットで考え、公開側の入口も閉じる |
| 注意点 | HTTPS で呼ぶ、秘密は URL に入れない、使っているエンドポイントとバージョンを一覧にする |
参考にした資料
この記事は、次の標準と公式ドキュメントで内容を確かめて書きました。仕様や対応状況は変わることがあるので、最新の情報はリンク先で確かめてください。
- RFC 3986: Uniform Resource Identifier (URI): Generic Syntax（IETF）：URL の部品、大文字小文字の扱い、フラグメント、URL に秘密を入れない理由
- RFC 6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage（IETF）：トークンを URL のクエリで送らない理由
- OpenAPI Specification v3.1.0（OpenAPI Initiative）：servers・paths・操作、パラメータの4つの置き場所
- Calling the Microsoft Graph API（Microsoft Learn）：Graph の URL の形、大文字小文字の扱い
- Microsoft Graph REST API v1.0 endpoint reference（Microsoft Learn）：v1.0 と beta、beta を本番で使わないこと
- List users・Create User（Microsoft Learn）：GET と POST の
/users - Microsoft Graph national cloud deployments（Microsoft Learn）：クラウドごとのエンドポイントとトークン
- Azure REST API reference（Microsoft Learn）：HTTPS の必要性、
api-version - Manage Azure resources by using the REST API（Microsoft Learn）：Azure Resource Manager のリクエスト例
- What is a private endpoint?（Microsoft Learn）：プライベートエンドポイントと DNS
- Use private endpoints for Azure App Service apps（Microsoft Learn）：公開アクセスの無効化
- API Versions（GitHub Docs）：
X-GitHub-Api-Versionヘッダとサポート期限
あとがき
表にしてみると、「エンドポイント」という一つの言葉が、サービスの入口を指したり、1つの操作を指したり、PC を指したりと、広い意味で使われていることがよくわかります。バージョンの書き場所も、同じ Microsoft の中でさえ Graph と Azure Resource Manager で違います。API の資料で迷ったときは、図2のように URL を部品に分けてみると、どこが共通でどこが操作ごとに変わるのかが見えてきます。
コメント