HTTP API

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

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

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

どちらの API タイプも、利用可能な API connectors の一覧にある HTTP API connector を使用して追加できます。

メリット

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

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

ユースケース

• クライアントサイドからのアクセスが制限されている API へのアクセス。
• IP ベースのアクセス制限がある API へのアクセス。
• リクエストに secrets を注入して、API に対してクライアントを認証する。
• 各 endpoint に security rules を提供し、認可されたクライアントのみが API にアクセスできるようにする。

HTTP API connector を作成する

HTTP connector を作成するには、次の情報を提供する必要があります:

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

接続情報を入力したら、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）と schema の定義

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

Squid の API connectors では、Squid Client SDK を介してリクエストとレスポンスをエンコード／デコードするために必要な詳細をまとめた schema の作成が必要です。この schema は、Squid と RESTful API の間に機能する接続を確立するうえで不可欠です。

schema は次の要素で構成されます:

Base URL

endpoint path が追加される 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 request 要素の詳細を示す fields で構成されます。

Response description

API response の詳細を示す fields で構成されます。

次は Squid Console で endpoint を編集している例です:

Injections

Injections は Squid の機能で、あらかじめ定義した値を各 API リクエストに挿入でき、API のやり取りにおける柔軟性とセキュリティを向上させます。この機能は、Squid Console で API schema レベルでグローバルに、または各 endpoint ごとに個別に設定できます。

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

Field name

値を注入する field の名前を指定します。

Location

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

Field value

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

Secret

injection field の値が secret であり、Squid Secret として保存されるべきであることを示すオプションのトグルです。

YOUR_CONNECTOR_ID とラベル付けされた endpoint を考えます。relative path は /YOUR_ENDPOINT_ID?someVar={mySecret} で、POST method を使用します。この構成では、mySecret という名前の injection field が 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 を参照してください。