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

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 へのアクセスとスキーマ自動検出を容易にし、Squid を通して API コールをルーティングすることでセキュリティを強化し、開発プロセスを簡素化します。認証済みクライアントのみにAPIアクセスを制限するために、個々のエンドポイントにセキュリティルールを適用することができます。

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

ユースケース​

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

HTTP API connector の作成​

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

  • Connector ID - 任意のIDです。簡潔かつ意味のあるものにするのが望ましい
  • OpenAPI specification URL - 通常 .yaml または .json で終わる OpenAPI仕様ファイルのURLです。これは 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
);

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

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

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

Squid Console API の概要

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

Base URL​

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

エンドポイント​

API内の異なるアクセスポイントの集合です。各エンドポイントに対してリクエストとレスポンスを定義できます。各エンドポイントには以下の定義が含まれます。

名前​

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

Relative path​

ベースURLに付加されて完全なエンドポイントURLを形成するパス（リクエストURLの query 部分を含む場合もあります）。パスパラメータを含める場合は、これらを中括弧で囲んでください（例: /YOUR_ENDPOINT_ID/{pathParam}）。

HTTP method​

API コールにデフォルトで使用される HTTP メソッドを指定します（例: GET, POST）。

リクエストの説明​

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

レスポンスの説明​

APIレスポンスの要素を詳細に記述するフィールドで構成されます。

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

Injections​

Injections は、各 API リクエストに事前定義された値を挿入する機能であり、API のやり取りにおける柔軟性とセキュリティを向上させます。この機能は Squid Console で、APIスキーマレベルでグローバルに、または各エンドポイント単位で個別に設定することができます。

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

Field name​

値が挿入されるフィールドの名前を指定します。

Location​

リクエスト内で値が配置される位置を決定します。現在、HEADER と QUERY の2つのオプションがサポートされています。

Field value​

指定されたフィールドに注入される実際の値です。これは直接の値である場合も、事前に構成された Squid secret から取得される場合もあります。

Secret​

注入フィールドの値が secret（シークレット）であり、Squid Secret として保存されるべきであることを示すオプションのトグルです。

たとえば、YOUR_CONNECTOR_ID というラベルのエンドポイントが、相対パス /YOUR_ENDPOINT_ID?someVar={mySecret} を持ち、POST メソッドを使用しているとします。この設定では、mySecret という名前の1つの injection フィールドが設定され、その配置場所は PATH に設定され、既存の Squid secret を参照し、その保存された値は my-secret-value となっています。

以下の例は、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 connector を保護するには、Secure API セクションを参照してください。

チュートリアル​

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