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 connector を使って追加できます。

メリット

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

さらに、この構成により、認証用のシークレットなどの機密情報を API リクエストに安全に注入（injection）できます。Squid はこれらのシークレットをリクエストを行うクライアントから隠したまま保持するため、API の完全性を維持し、セキュリティを強化できます。

ユースケース

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

HTTP API connector を作成する

HTTP connector を作成するには、次の情報を指定する必要があります。

• Connector ID - 任意の ID。短く、意味のあるものにするのがベストです
• OpenAPI specification URL - OpenAPI 仕様ファイルの URL（通常は .yaml または .json で終わります）。これは OpenAPI API に接続する場合にのみ必要です。このフィールドを空欄にした場合でも、connector を追加した後に API スキーマファイルをアップロードすることもできます。

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

API connector を使う

connector を作成したら、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
);

自動検出（Autodiscovery）とスキーマ定義

OpenAPI specification の endpoint では、Squid Console がスキーマを自動検出するため、設定プロセスがより正確で便利になります。Endpoints は tag に基づいて自動的にグループ化され、検索もできるため、endpoint の長いリストでも扱いやすくなります。API が OpenAPI spec を使用していない場合は、コンソールでスキーマを手動定義できます。

Squid の API connectors では、Squid Client SDK を通じてリクエストとレスポンスをエンコード／デコードするために必要な詳細を定義するスキーマの作成が必要です。このスキーマは、Squid と RESTful APIs の間に機能する接続を確立するために不可欠です。

スキーマは次の要素で構成されます。

Base URL

endpoint のパスを付加する基点となる base URL。

Endpoints

API 内のさまざまなアクセスポイントの集合。各 endpoint について、request と response を定義できます。各 endpoint には次の定義が含まれます。

Name

endpoint の一意の識別子。

Relative path

base URL に付加して完全な endpoint URL を形成するパス（リクエスト URL の query 部分を含めることもできます）。path parameters を含める場合は、必ず括弧で囲んでください（例: /YOUR_ENDPOINT_ID/{pathParam}）。

HTTP method

API 呼び出しでデフォルト使用する HTTP method（例: GET、POST）を指定します。

Request description

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

Response description

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

以下は、Squid Console で endpoint を編集する例です。

Injections

Injections は Squid の機能で、各 API リクエストに事前定義した値を挿入できるようにし、API 連携の柔軟性とセキュリティを高めます。この機能は、Squid Console で、API スキーマレベルでグローバルに設定することも、endpoint ごとに個別設定することもできます。

injection を設定するには、次の要素を構成します。

Field name

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

Location

値をリクエスト内のどこに配置するかを決定します。現在は HEADER と QUERY の 2 つのオプションをサポートしています。

Field value

指定したフィールドに注入する実際の値。直接値を指定することも、事前に設定した Squid secret から取得することもできます。

Secret

injection フィールドの値がシークレットであり、Squid Secret として保存すべきであることを示す任意のトグル。

relative path が /YOUR_ENDPOINT_ID?someVar={mySecret} で、POST method を使用する YOUR_CONNECTOR_ID というラベルの endpoint を考えます。このセットアップでは、mySecret という名前の injection フィールドが 1 つ設定されており、location は 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

Security rules の要件

Squid Client SDK を使用して endpoint にアクセスするための security rules を指定できます。

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

チュートリアル

外部 HTTP API を Squid と統合する完全な例を確認するには、Cat Facts API Tutorial を参照してください。