メインコンテンツまでスキップ

HTTP API

Squid を任意の HTTP API に接続し、リクエストとレスポンスをマッピングすることで、Squid Client SDK を使用してアクセスできるようにします。​

Squid は 2 種類の HTTP API をサポートしています:

  1. REST APIs - HTTP プロトコルを使用して CRUD 操作を実行する API
  2. OpenAPI APIs - OpenAPI 仕様を使用して API を定義する API

どちらの API タイプも、利用可能な API connectors リストにある HTTP API コネクタを使用して追加できます.

利点​

Squid Client SDK は API へのアクセスやスキーマの自動検出を容易にし、API 呼び出しを Squid 経由でルーティングすることでセキュリティを強化し、開発プロセスを簡素化します。API へのアクセスを許可されたクライアントのみに限定するために、個々のエンドポイントにセキュリティルールを適用することができます.

さらに、このセットアップでは、認証シークレットなどの機密情報を API リクエストに安全に注入することが可能です。Squid はリクエストを行うクライアントからこれらのシークレットを隠すため、API の整合性が保たれ、セキュリティが強化されます.

ユースケース​

  • クライアント側からのアクセスが制限されている API へのアクセス。
  • IP アドレスベースのアクセス制限がある API へのアクセス。
  • クライアントの API 認証のために、リクエストにシークレットを注入すること。
  • 各エンドポイントにセキュリティルールを提供し、認証されたクライアントのみが API にアクセスできるようにすること。

HTTP API コネクタの作成​

HTTP コネクタを作成するには、以下の情報を入力する必要があります:

  • Connector ID - お好みの ID。簡潔かつわかりやすいものが望ましいです
  • OpenAPI specification URL - OpenAPI 仕様ファイルの URL（通常、.yaml または .json で終わります）。これは OpenAPI API に接続する場合にのみ必要です。このフィールドを空白のままにした場合、コネクタ追加後に API スキーマファイルをアップロードすることもできます.

接続情報を入力したら、Next ボタンをクリックして続行します.

API コネクタの使用​

コネクタを作成したら、Squid Client SDK を使用して HTTP API にアクセスします。以下の例は、追加オプション付きの POST リクエストを示しています:

Client code
const response = await squid.api().request(
  'YOUR_INTEGRATION_ID',
  'YOUR_ENDPOINT_ID',
  { user_name: 'newUser1 ' }, // request body
  {
    headers: { api_key: YOUR_API_KEY }, // optional headers
    queryParams: { new_user: true }, // optional query parameters
    pathParams: { 'subscriber-group': 42 }, // optional path parameters
  },
  'post' // request method
);

自動検出とスキーマの定義​

OpenAPI 仕様のエンドポイントでは、Squid Console が自動的にスキーマを検出するため、設定プロセスがより正確かつ利便性が向上します。エンドポイントはタグに基づいて自動的にグループ化され、検索可能になるため、長いリストのエンドポイントを扱いやすくなります。API が OpenAPI 仕様を使用していない場合は、Console 内で手動でスキーマを定義することができます.

Squid の API コネクタでは、Squid Client SDK を通してリクエストとレスポンスをエンコードおよびデコードするために必要な詳細を概説するスキーマの作成が必要です。このスキーマは、Squid と RESTful API 間の機能的な接続を確立するために不可欠です.

Squid Console API の概要

スキーマは次の要素から構成されます:

ベース URL​

エンドポイントパスが追加されるベース URL.

エンドポイント​

API 内のさまざまなアクセスポイントの集まりです。各エンドポイントについて、リクエストとレスポンスを定義できます。各エンドポイントには、以下の定義が含まれます.

名前​

エンドポイントの一意の識別子.

相対パス​

ベース URL に追加されて完全なエンドポイント URL を形成するパス（リクエスト URL の query 部分を含む場合もあります）。パスパラメータを使用する場合は、必ず角括弧で囲むようにしてください（例: /YOUR_ENDPOINT_ID/{pathParam}）.

HTTP メソッド​

API 呼び出しでデフォルトで使用される HTTP メソッド（例: GET, POST）を指定します.

リクエストの説明​

API リクエストの要素を詳細に示すフィールドから構成されます.

レスポンスの説明​

API レスポンスの詳細を示すフィールドから構成されます.

以下は Squid Console でエンドポイントを編集する様子です: エンドポイントの編集

インジェクション​

インジェクションは、各 API リクエストに事前定義された値を挿入することで、API とのやりとりの柔軟性とセキュリティを高める Squid の機能です。この機能は、Squid Console で、API スキーマレベルでグローバルに、または個々のエンドポイントごとに個別に設定することができます.

インジェクションを設定するには、以下の要素を構成してください:

フィールド名​

値を注入するフィールドの名前を指定します.

場所​

リクエスト内のどこに値を配置するかを決定します。現在、HEADER および QUERY の 2 つのオプションがサポートされています.

フィールド値​

指定されたフィールドに注入される実際の値です。直接の値でも、事前に設定された Squid secret から取得された値でも構いません.

Secret​

インジェクションフィールドの値がシークレットであり、Squid Secret として保存すべきであることを示すオプションのトグルです.

例えば、相対パスが /YOUR_ENDPOINT_ID?someVar={mySecret} で、POST メソッドを使用する YOUR_CONNECTOR_ID というエンドポイントを考えてみてください。この設定では、mySecret という名前の 1 つのインジェクションフィールドが設定され、その場所が PATH に設定され、保存された値 my-secret-value の既存の Squid secret を指しています.

以下の例は、Squid Client SDK からこの API を呼び出す方法を示しています:

Client code
const result = await squid.api().request('YOUR_CONNECTOR_ID', 'YOUR_ENDPOINT_ID');

その結果、Squid は次の HTTP リクエストを実行します:

POST /YOUR_ENDPOINT_ID?someVar=my-secret-value

セキュリティルールの要件​

Squid Client SDK を使用してエンドポイントにアクセスする際、セキュリティルールを指定するオプションがあります.

HTTP API コネクタを保護するには、Secure API セクションを参照してください.

チュートリアル​

外部 HTTP API を Squid と統合する完全な例を見るには、Cat Facts API Tutorial をご覧ください.