APIエンドポイントとは？ソフトウェア連携ガイド

API（アプリケーションプログラミングインターフェース）エンドポイントとは、APIがリクエストを受信し、レスポンスを返す特定のURLです。

APIエンドポイントは、アプリケーションがサーバーに接続してデータをリクエストしたり、コマンドを実行したりするための正確なWebアドレスです。従来のアーキテクチャも引き続き使われていますが、最新のアプリケーションでは、さまざまなサービス間のHTTPリクエスト処理にREST APIが利用されています。

このガイドでは、エンドポイントがリクエストを処理する仕組み、API呼び出しの形式、実稼働環境でAPIエンドポイントのセキュリティを維持する方法を解説します。また、ElevenAPIを使ってシステムをスムーズに接続し、実稼働に対応したオーディオワークフローを構築する方法も紹介します。

概要

• APIエンドポイントとは、APIがリクエストを受信し、レスポンスを返す特定のURLです。
• クライアントアプリケーションとサーバーインフラの間に自動通信経路を設けることで、データ交換とシステムインテグレーションがスムーズになります。
• 一般的な7種類のAPIには、REST APIエンドポイント、SOAP、GraphQL、RPC、WebSocket、gRPC、Web APIがあります。
• APIエンドポイント設計の一般的なベストプラクティスには、直感的なリソースベースの命名や、標準化されたHTTPステータスコードと構造化されたJSONエラーペイロードの組み合わせがあります。
• エンジニアリングチームは、HTTPコードの検証、基本的なリクエスト接続の確認、リアルタイムの同時実行数の追跡によって、APIエンドポイントをテスト・監視します。
• APIエンドポイントを保護するには、キーベースの認証、最小権限に基づく権限範囲の設定、同時実行数ベースのレート制限が必要です。

APIエンドポイントの仕組み：リクエスト、レスポンス、ルート

APIエンドポイントは、APIがリクエストを受信し、レスポンスを返すために使うデジタル上の場所です。クライアントアプリケーションは、このエンドポイントに紐づく特定のURLを使ってサーバーリソースにアクセスします。

各エンドポイントルートでは、HTTPメソッドとリソースパスを組み合わせて、個別のやり取りを処理します。クライアントがそのルートにリクエストを送信すると、サーバーがデータを処理し、ステータスコードとともにレスポンスを返します。

たとえば、アプリケーションがユーザーのメタデータをリクエストしたり、データペイロードを送信したりする場合、APIサーバー上にある指定のエンドポイントURLへHTTPリクエストを送ります。

API、エンドポイント、URLの違いとは？

API、APIエンドポイント、URLという用語は一緒に使われることが多いものの、ソフトウェアアーキテクチャではそれぞれ異なる要素を表します。

APIは、2つのアプリケーションが通信するためのルールとプロトコルを定めた、ソフトウェアインターフェース全体です。一方、APIエンドポイントは、アプリ間の双方向通信に使われる、サーバー上の特定のデジタル入口です。URLは、クライアントアプリケーションがネットワーク経由でそのエンドポイントを特定し、接続するために使う完全なWebアドレス文字列です。

API、エンドポイント、URLの主な違いは次のとおりです。

• 範囲とアーキテクチャ：APIはルールとデータ契約のシステム全体を指しますが、APIエンドポイントは特定の場所を1つだけ指し、URLはその場所のアドレスです。
• 機能と目的：APIはソフトウェアコンポーネント同士の連携方法を定めます。APIエンドポイントは特定の機能やデータリソースへのアクセスを提供し、URLはクライアントアプリケーションにAPI呼び出しの送信先を正確に示します。
• 構成：1つのAPIには複数のエンドポイントがありますが、各APIエンドポイントでは特定のリソースパスとHTTPメソッドが対応します。URLも、ネットワークプロトコル、ドメイン名、エンドポイントパス、クエリパラメータなど、複数の要素で構成されます。

APIエンドポイントはどのように機能しますか？

APIエンドポイントでは、クライアントアプリケーションとサーバーの間で構造化されたリクエストとレスポンスのサイクルが使われます。通常は次の手順で進みます。

1. 開始：クライアントがエンドポイントURLに直接HTTPリクエストを送信します。このリクエストには、HTTPメソッド、HTTPヘッダー、任意のクエリパラメータ、任意のリクエスト本文データが含まれます。
2. 検証と処理：サーバーがリクエストを受信し、クライアントの認証情報を確認して、アクセス権限を検証します。その後、バックエンドシステムが内部データベースを照会するか、サーバー側のビジネスロジックを実行して、要求された処理を行います。
3. レスポンスの返却：サーバーは出力を構造化されたJSONペイロードにまとめます。そのペイロードを、処理の成功を示す、または発生したエラーの詳細を示すHTTPステータスコードとともにクライアントへ返します。
4. インテグレーションの実行：クライアントアプリケーションは返されたペイロードを解析し、ユーザーインターフェースの更新、データ処理、後続アクションの起動を行います。

REST APIエンドポイントと使用するHTTPメソッド

REST APIエンドポイントでは、クライアントがサーバーリソースに対して実行する操作を、標準のHTTPメソッドで定義します。GETリクエストはデータを読み取り、バックエンドのリソースを変更しません。一方、POSTリクエストは新しいデータを送信してリソースを作成したり、サーバー側の処理を起動したりすることで、データを書き込みます。

また、既存のレコードを変更するにはPUTまたはPATCHリクエストを使い、データベースから特定のリソースを削除するにはDELETEを使います。 

ElevenAPIのインテグレーションでは、主にGETリクエストとPOSTリクエストを使用し、リアルタイムオーディオにはストリーミングとWebSocketエンドポイントを利用します。GETエンドポイントは利用可能な音声とモデルのメタデータを取得し、POSTエンドポイントはテキスト読み上げ合成などの生成タスクを実行します。

APIエンドポイントの例：一般的なリクエストを実例で解説

ElevenAPIの実際のリクエストを見ると、実稼働環境でAPIエンドポイントがどのように機能するかを理解できます。 

ElevenAPIでは、各エンドポイントルートが、システムメタデータの取得やオーディオ生成など、特定のタスクを実行するHTTPメソッドに対応しています。クライアントアプリケーションは、情報を取得するためにGETリクエストを送信し、データの送信や処理タスクの実行にはPOSTリクエストを使います。 

実稼働環境での主要ルートの仕組みは次のとおりです。

読み取りリクエスト

GET https://api.elevenlabs.io/v1/modelsは、利用可能な音声合成モデルとその機能の一覧を取得します。このリクエストでは、認証のためにxi-api-key HTTPヘッダーが必要ですが、リクエスト本文は不要です。サーバーがクエリを処理し、モデルの詳細を含むJSONペイロードを返します。

書き込みリクエスト

POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id}は、オーディオを生成するためのペイロードデータをサーバーへ送信します。アプリケーションは、テキスト読み上げ合成を実行するため、textやmodel_idなどのパラメータを含むJSON本文を送信します。エンドポイントはこれらのパラメータを処理し、形式を整えたオーディオをアプリケーションへストリーミングします。

curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb?output_format=mp3_44100_128" \
     -H "xi-api-key: xi-api-key" \
     -H "Content-Type: application/json" \
     -d '{
  "text": "The first move is what sets everything in motion.",
  "model_id": "eleven_multilingual_v2"
}'

詳しくは、テキスト読み上げAPIリファレンスをご覧ください。

一般的な7種類のAPIとその用途

開発チームは、データ転送の要件に応じて、一般的な7種類のAPIアーキテクチャから選択します。 

ElevenAPIは、効率を最大化して遅延を最小限に抑えるため、複数のアーキテクチャスタイルを1つのプラットフォームに統合しています。通常、標準的なリクエストにはRESTを、リアルタイムオーディオのストリーミングにはWebSocketプロトコルを使います。

予測しやすいインテグレーションを実現するAPIエンドポイント設計のベストプラクティス

設計のベストプラクティスに従うことで、基盤となるプラットフォームが変化したり、ユースケースが拡大したりしても、APIエンドポイントの安定性、保守性、耐障害性を維持できます。ElevenAPIでは、次のような明確なRESTルールを採用し、エンジニアリングチームのインテグレーションを簡単にしています。

• 直感的なリソースベースの命名とバージョニング：エンドポイントのパスには、提供するリソースを直接表す名詞を使用し、アクションを示す明確なHTTPメソッドと組み合わせます。例：/v1/models or /v1/text-to-speech/{voice_id}。
• 標準化されたHTTPステータスコードと構造化されたエラーペイロード：予測しやすいエンドポイントは、標準のHTTPステータスコードを返し、リクエストの正確な結果を示します。これらのステータスコードと構造化されたJSONエラーペイロードを組み合わせることで、クライアントソフトウェアは、リクエストパラメータを修正するか、バックオフを伴う再試行を行うかをプログラムで判断できます。
• 型安全なSDKとSDKパラメータの検証：PythonやTypeScriptなどの言語向けに公式の強く型付けされたSDKを提供することで、インテグレーションが簡単になります。また、ネットワーク呼び出しがクライアントから送信される前に、リクエストスキーマを適用できます。

APIエンドポイントをテスト・監視する方法

APIエンドポイントを早い段階でテストすると、デベロッパーがアプリケーションロジックを記述する前に、認証とネットワーク接続を確認できます。 

xi-api-key HTTPヘッダーを使ってGET https://api.elevenlabs.io/v1/modelsへリクエストを送信（またはcurl https://api.elevenlabs.io/v1/modelsを実行）し、認証情報とネットワークアクセスを検証して、利用可能なモデルを取得します。 

次に、ライブトラフィックを監視し、HTTP 429エラーレスポンスを確認します。エンジニアリングチームは指標を追跡して予期しない使用量の急増を検出し、それに応じて送信リクエストのレートを調整します。

too_many_concurrent_requestsエラーは、アカウントがプランの同時実行数上限に達したことを示します。処理中のリクエストが完了するまで待つか、上位プランへ変更してください。一方、system_busyエラーは、プラットフォームが一時的に混雑していることを示します。通常はリクエストを再試行すると成功します。

APIエンドポイントのセキュリティ：認証、認可、レート制限

APIエンドポイントを保護するには、秘密の認証情報を守ると同時に、各認証情報で実行できる操作にきめ細かな制限を設ける必要があります。ElevenAPIでは、推奨されるベストプラクティスに加えて3つの主要な仕組みを使い、バックエンド処理とクライアントインテグレーションを保護しています。

1. 認証

すべてのリクエストで、秘密の認証情報をxi-api-key HTTPヘッダーに含めます。長期間有効なAPIキーは必ず安全なサーバー上で管理し、ブラウザやモバイルアプリなどのクライアント側コードに公開してはいけません。クライアント側のScribeおよびテキスト読み上げのWebSocket接続では、サーバーが使い捨てトークンを発行するため、長期間有効なキーを安全に保護できます。

使い捨てトークンは15分後に期限切れとなり、初回使用時に消費されます。詳しくは、使い捨てトークンのドキュメントをご覧ください。

2. 認可とスコープ設定

開発、ステージング、実稼働の各環境に個別のキーを発行します。次に、以下の3つのきめ細かなセキュリティ機構に基づいて各キーを設定します。

• エンドポイントへのアクセス：APIが呼び出せるエンドポイントを制限し、各認証情報には実行する処理に必要な権限だけを付与します。たとえば、スピーチtoテキストの文字起こし専用キーに、テキスト読み上げの生成権限は必要ありません。
• クレジット上限：キーごとにカスタムのクレジット上限を設定し、予想外の大量消費による金銭的リスクを抑え、アプリケーションコードの実行ループを封じ込め、キーが漏えいした場合にもアカウント残高を保護します。
• IP許可リスト：エンタープライズアカウントでは、キーの使用を特定のIPアドレスまたはCIDR範囲に制限できます（現在プレビュー版で、アカウントマネージャーを通じて利用可能）。それ以外のIPからのリクエストは、HTTP 403エラーで拒否されます。

レート制限

レート制限は、単純な1分あたりの割り当てではなく、同時実行数に基づきます。特定のモデルファミリー全体で、同時に実行できる生成処理や処理中のリクエスト数を制限します。

ElevenAPIで音声と会話型AIのワークフローを構築

ElevenAPIでは、音声エージェント、テキスト読み上げ、スピーチtoテキストなど、幅広いAIオーディオ機能をプログラムから利用できます。モデル全体で低遅延、豊かな感情表現、90以上の言語への対応を実現し、人間らしいオーディオを技術スタックに直接組み込めます。これにより、カスタマーサポート、従業員研修、コンテンツ制作、マーケティングなど、ビジネスソリューションを支えるテクノロジーの可能性が広がります。

リアルタイムの会話型エージェントを導入する場合でも、多言語ローカライゼーションを自動化する場合でも、ElevenAPIは実稼働アプリケーションに必要なインフラ、速度、セキュリティを提供します。 

ElevenAPIでエンドポイントリファレンスやインテグレーションのクックブックを確認するか、APIキーをリクエストして今すぐ開発を始めましょう。

APIエンドポイントに関するよくある質問