APIのエンドポイントは、APIの入口としてクライアントからサーバーに通信するために不可欠な要素になります。本文では、APIエンドポイントの概念、仕組み及び具体例を紹介した上、それを簡単にテストする方法を解説します。
Apidogは、個人向け永久無料のAPIクライアントとして、次のボタンから無料で利用し始めましょう。👇👇👇
APIエンドポイントとは
APIエンドポイントは、Webサービスやアプリケーションにおいて、外部のクライアントがAPI（Application Programming Interface）との通信を行うための特定のURLまたはURI（Uniform Resource Identifier）になり、リクエストが実行される場所を指します。APIエンドポイントは一般的に、RESTfulなAPI設計の一部として使用されます。
APIエンドポイントは、クライアントが特定の機能やデータにアクセスするための入り口となります。クライアントはHTTPリクエスト（GET、POST、PUT、DELETEなど）を使用してAPIエンドポイントにリクエストを送信し、応答を受け取ります。APIエンドポイントは、リクエストに基づいて適切な処理を行い、クライアントにレスポンスを返します。
APIエンドポイントの仕組み
①通信用プロトコル
APIエンドポイントには、通信プロトコルを含む必要があります。例えば、よくみられるRestful ウェブAPIは、HTTPプロトコルを使っているので、APIエンドポイントのURLにhttpが含まれる必要があります。
②APIサーバー
APIのサーバーは、データを保存し、アプリを実行する専用のコンピュータです。APIは常に単一または複数のサーバーでホストされます。APIエンドポイントでAPIサーバーを指定するために、エンドポイントにAPIサーバーのアドレスが含まれる必要があります。
APIサーバーアドレスの例は、次のような形式で表されます。
ドメイン名を使用した例:
- api.example.com: APIがexample.comドメインの下にホストされている場合。
- example-api.com: 別のドメインでAPIがホストされている場合。
IPアドレスを使用した例:
- 192.168.0.1: APIが特定のIPアドレス上にホストされている場合。
ポート番号を指定した例:
- api.example.com:8080: APIが特定のポート番号（8080）でホストされている場合。
③具体的なパス
具体的なパスは、リクエストがAPIサーバーのどこかで実行されるという追加の情報になります。例えば、"/v1/users"のような具体的な場所情報を追加する必要があります。
APIエンドポイントの具体例
完全のAPIエンドポイントには、上記の3つの要素が含まれる必要があります。これら3つの要素を組み合わせると、完全なAPIエンドポイントになります。
ここでhttps://api.example.com/v1/usersというエンドポイントでその構造を説明します。
- "https://"：これはセキュアなHTTPプロトコル（HTTPS）を使用して通信することを示しています。データの送受信が暗号化され、セキュリティが強化されます。
- "api.example.com"：これはAPIサーバーのドメイン名です。APIがホストされているドメインを識別します。
- "/v1/users"：これはAPIのバージョンと具体的なAPIリソース（リクエストの実行場所）を示すパスセグメントです。"/v1/"がAPIのバージョニングを行って、"/users"はAPIサーバーで具体的な場所になります。
APIエンドポイントとURLパラメータ
また、GETリクエストは、よくクエリパラメータやパスパラメータを利用してデータを渡しています。クエリパラメータとパスパラメータともURLパラメータになるので、直接にAPIエンドポイントの後に追加されます。
同じく上記のエンドポイント「https://api.example.com/v1/users」を例にする場合：
APIエンドポイント＋パスパラメータ
パスパラメータで特定のユーザーデータを取得するために、具体的なユーザーIDを直接にAPIエンドポイントに追加してリクエスを送信する必要があります：「https://api.example.com/v1/users/12345」
ここで12345がAPIエンドポイントではなく、パスパラメータになります。
APIエンドポイント＋クエリパラメータ
また、APIエンドポイントに対して、クエリパラメータを利用してデータソースを指定することができます。
「https://api.example.com/v1/users?name=田中gender=male」
ここで「?name=田中gender=male」がクエリパラメータで、ユーザー名が田中、性別が男であるユーザーを検索できます。このようにクエリパラメータはKEY=VALUEの形（キーと値のペア）で指定し、複数のパラメータを追加する場合は、&符号で繋げて指定することができます。
要するに、パスパラメータとクエリパラメータは直接にエンドポイントのURLに追加されますが、APIのエンドポイントにもなっているとは言い難いので、APIエンドポイントということを理解する時に、これらの概念を区別することに注意を払う必要があると思います。
APIエンドポイントとAPI：多くの場合で同じことを意味
厳密にいう場合は、APIエンドポイントとAPIが異なる概念ですが、同じ意味で使われることが多いのは事実です。実務でははっきりと区別されないことが多くあります。
特に、「そのAPIのエンドポイントは何ですか?」のように、APIの入り口となるURLそのものを指して、エンドポイントとAPIを同じ言葉で表現することがよくあります。
つまり、文脈から以下のようにAPIエンドポイントとAPIが同義で使われていると解釈できる場合が多いということです。
- 「このAPIを叩く」= 「このAPIのエンドポイントにリクエストを送る」
- 「APIの仕様を確認する」= 「そのAPIエンドポイントの仕様を確認する」
なので、状況によってはAPIエンドポイントとAPIを同じ意味ととらえても問題ない場合がほとんどだと言えます。しっかりとした区別が必要な技術的な文書以外では、同義と考えて違和感はないでしょう。
ApidogでAPIエンドポイントをテストする
APIエンドポイントを持っていると、そこにリクエストを送信して、適切なレスポンスを取得できるかを検証するために、APIエンドポイントの単体テストを行う必要がよくあります。このような場合、ApidogというAPI管理ツールを使用すること、簡単に実現できます。
APIエンドポイントのテストにHTTPメソッドの指定も必要
APIエンドポイントは、クライアントからのリクエストを受け付ける入口ですが、その際に実行される処理はHTTPメソッドによって異なります。
例えば、同じエンドポイントでもGETメソッドならデータの取得を、POSTメソッドなら新規データの作成を、PUTならデータの更新を、DELETEならデータの削除を行います。そこで、テストでは、実際の利用を想定してそれぞれの処理が期待される動作をしているかを確認する必要があるため、リクエスト時のHTTPメソッドを明示的に指定することが大切なのです。
Apidogでのテストも、エンドポイントだけでなくメソッドを選択することで、そのエンドポイントが全てのAPI操作に対して適切に対応できているかを効率的に検証できるという利点があります。
ApidogでAPIエンドポイントをテストする操作手順
ステップ⒈APIの実行ページで、APIエンドポイントをアドレスバーに入力して、必要に応じて、HTTPメソッドやパラメータを入力して、「送信」ボタンをクリックするだけで、HTTPリクエストを送信できます。
ステップ⒉ここでAPIエンドポイントからレスポンスをすぐ取得できます。Apidog アプリは、API定義書を参照して、取得したレスポンスが正確であるかどうかを自動的に検証してくれます。
Apidogで上記のような手順でAPIエンドポイントをテストしたりすることができます。
まとめ
APIエンドポイントは、クライアントとAPIサーバーの間でデータ通信を行うための入口であり、通信プロトコル、APIが稼働しているサーバー、リクエスト実行場所のパスから構成されます。GETリクエスト時には、エンドポイントにパスパラメータやクエリパラメータを追加して使用することも多いですが、パラメータの部分がAPIのエンドポイントとは別のものになることにも注意を払ってください。
このAPIエンドポイントを簡単にテストできるツールにApidogがあります。Apidogではエンドポイントを入力し、必要なパラメータを設定してリクエストを送信するだけで、そのエンドポイントからレスポンスを取得し、API定義と突き合わせた検証を自動で行ってくれます。
GUIベースのApidogなら、プログラミング不要で手軽にエンドポイントをテストできるので、API開発者やテスターにとって大変便利なツールといえます。API利用の入り口であるエンドポイントの概念と検証方法を理解しておくことが大切です。
