HTTP API を統合する

Squid は任意の API と統合できるため、complex migration を必要とせずに複数 data source で Squid の power を活用できます。

TL;DR

この tutorial では React と Squid を使用して sample Cat Facts API に接続し、cat に関する random fact を表示します。React と Squid platform の基本的な理解は役立ちますが、この guide に前提条件はありません。

完成版の app を確認するには、GitHub 上の Squid HTTP API sampleを参照してください。

新しい React Project を作成する

まず、この project のすべての file を格納する新しい directory を作成します。

mkdir api

次に root directory に cd し、Vite を使用して新しい React typescript application を作成します。これにより project の frontend が作成されます。

npm create vite@latest api-frontend -- --template react-ts

次に、新しく作成された directory に移動し、すべての dependency を install します。

cd api-frontend
npm install

Console で新しい App を作成する

Squid Console に移動し、api という名前の新しい application を作成します。

注記

Squid は development と production 用に 2 つの異なる target environment を提供します。この tutorial では dev environment を使用しますが、prod も option として利用できます。 application を機能させるには、project 全体で同じ target environment を使用していることを確認してください。詳細については、Squid の environmentを参照してください。

console の step に従って backend template project を生成します。これらの step を表示するには、overview page の Initialize backend と Create .env file をクリックします。frontend と backend directory が sibling になるよう、backend を初期化する前に root project directory に cd して戻ってください。

API Connector を作成する

注記

この tutorial では、"integration" と "connector" は同じ concept を指す interchangeable な term として使用します。

console で application の Connectors page に移動し、新しい API connector を追加します。connector は environment 間で共有されないため、正しい environment（development 用では通常 dev）を使用していることを確認してください。

新しい API connector を追加

Connector ID と OpenAPI specification URL の 2 つの input field に value を入力します。

ID には、catFacts など、この connector が表すものを示す意味のある value を選択します
OpenAPI specification は API を document 化する standardized な方法です。URL は API により提供され、API の home page で確認できます: https://catfact.ninja/docs?api-docs.json

この URL を指定すると Squid の API への connection が確立されます。Next button をクリックすると、Squid が API Schema を自動 discover します。 API に change が加えられた場合は、手動で Rediscover schema することもできます（この tutorial では必要ありません）。

Cat Facts API への connection を finalize するには、connector screen の左上にある Base URL を edit します。base URL はこの API のすべての available endpoint の initial path を提供します。URL は sample query を実行すると API の home page で確認できます。Cat Facts API の URL は https://catfact.ninja です。
Save Schema をクリックして API を project に追加します。

Connector を理解する

API connector を追加したので、使用方法をさらに理解できます。connector の Schema page には、Squid が自動 discover したすべての endpoint が list 化されます。

例として、getRandomFact endpoint をクリックします。

getRandomFact endpoint をクリック

この view には、各 endpoint を利用するために必要なすべての information が表示されます。

URL: この endpoint を使用する path を説明します。
Request: この endpoint に必要な option の list を提供します。getRandomFact では fact の max_length を指定する必要があります。
Injections: header または body に、endpoint のすべての request 用の追加 field を inject します。API Key などの secret value の保存に使用できます。Cat Facts API には API Key が不要なため、injection を追加する必要はありません。
Response: この endpoint の consume 後の response の形式を説明します。getRandomFact の response には、cat の fact と fact の length の 2 field が含まれます。

この information を使用して、project 内で connector を使用する準備ができました。

Security Rule

すべての external API integration には security rule が必要です。これにより、integration と specific endpoint への access を authorize する custom logic を作成できます。authentication と authorization はこの tutorial の scope 外であるため、catFacts integration へのすべての access を許可する security rule を作成します。

ヒント

data の保護について詳しくは、Squid backend の security ruleを参照してください。

security rule は api-backend/src/service/example-service.ts file にあります。SquidService class に decorator を追加すると security rule を拡張できます。API integration 用の security rule を作成するには、INTEGRATION_ID（CONNECTOR_ID）を parameter に取る @secureApi decorator を使用します。ExampleService class に新しい security rule を作成します。

Backend code
import { secureApi, secureDatabase, SquidService } from '@squidcloud/backend';
import { ApiCallContext } from "@squidcloud/client";

...

export class ExampleService extends SquidService {

  ...

  @secureApi('catFacts')
  secureCatFacts(context: ApiCallContext): boolean {
    return true; // Allows all access to the catFacts integration
  }
}

Client で API を使用する

最後の step は、Squid React SDK を使用して React project 内で connector を使用することです。

Setup

api-frontend directory に Squid React SDK を install します。

npm install @squidcloud/react

src/main.tsx で、.env file にある configuration option を使用して App component を SquidContextProvider で wrap します。.env file は、console で app を作成する際に自動生成されました。

Client code
import { SquidContextProvider } from '@squidcloud/react';


...

ReactDOM.createRoot(document.getElementById('root')!).render(
    <SquidContextProvider
      options={{
        appId: 'YOUR_APP_ID',
        region: 'YOUR_REGION', // example: 'us-east-1.aws'
        environmentId: 'dev | prod', // choose one of 'dev' or 'prod'
        squidDeveloperId: 'YOUR_SQUID_DEVELOPER_ID',
      }}
    >
      <App />
    </SquidContextProvider>
);

App.tsx

新しい connector を使用するよう src/App.tsx を edit します。

Squid React SDK の squid.api().request() method を使用して、API connector 内の endpoint を使用できます。request() method は 3 つの parameter を取ります。

integrationId: connector の name は catFacts
endpointId: console で API schema を discover した後、getRandomFact を使用
body object: 前述のとおり、request には max_length が必要

request() method は promise を返します。

Client code
squid.api().request('catFacts', 'getRandomFact', { max_length: 70 });

次に、App component 内でこの method を invoke できます。まず connector が返す fact を track するための React stateを作成します。request function を invoke した後、新しい fact data を使用して state を update できます。request は promise を返すため、promise が resolve された後で data に access するには .then method を使用する必要があります。React の trick として、call を useEffect hook で wrap し、1 回だけ実行されるようにします。

Client code
function App() {
  const squid = useSquid();

  /* The endpoint's response object has a fact and its length. This can be
   * verified in the console */
  const [randomFact, setFact] = useState({ fact: '', length: 0 });

  useEffect(() => {
    squid
      .api()
      .request('catFacts', 'getRandomFact', { max_length: 70 })
      .then((data) => {
        setFact(data.body as RandomFact);
      });
  }, []);
}

catFact state の fact field に access して、page に fact を render します。完全な App.tsx は以下のとおりです。

Client code
import { useEffect, useState } from 'react';
import { useSquid } from '@squidcloud/react';
import './App.css';

interface RandomFact {
  fact: string;
  length: number;
}

function App() {
  const squid = useSquid();
  const [randomFact, setFact] = useState({ fact: '', length: 0 });

  useEffect(() => {
    squid
      .api()
      .request('catFacts', 'getRandomFact', { max_length: 70 })
      .then((data) => {
        setFact(data.body as RandomFact);
      });
  }, []);

  return (
    <>
      <div>
        Fact: {randomFact?.fact} <br />
        Length: {randomFact?.length}
      </div>
    </>
  );
}

export default App;

Project を実行する

project を実行するには、client React project と backend Squid project の両方を開始する必要があります。

backend を実行するには、api-backend folder から以下を実行します。

squid start

client を実行するには、2 つ目の terminal window を開き、root folder から以下を実行します。

npm run dev

これで client project は terminal に log 出力された port の http://localhost:PORT で実行されます。page には fact とその character 単位の length が表示されます。新しい random cat fact を表示するには page を refresh します。

おめでとうございます！わずか数分で、Squid を使用した最初の API integration を正式に setup できました！

次のステップ

Squid API integration の capability について詳しくは、API の call に関する Client SDK documentationを参照してください。HTTP API endpoint の security を customize する方法については、Backend SDK documentationを参照してください。

Bonus: HTTP Header を組み込む

API integration には、secret を含む specialized header が必要になることがよくあります。Squid では、console でこれらの value をすばやく構成し、安全に access して secured endpoint に request を実行できます。

これを示すために、request に API key を必要とする別の cat facts API を使用します。この API には利用可能な OpenAPI spec がないため、schema を手動で追加する方法も説明します。

Random Cat Fact API に subscribe します。この API には $0 subscription があります。RapidAPI account がない場合は作成する必要があります。subscribe すると、RapidAPI key で endpoint に接続できます。
Squid Console で、新しい HTTP API integration を追加します。integration には catFacts2 という ID を付けます。
Add Connector をクリックします。この API には OpenAPI spec がないため、Open API spec の URL は空欄にします。
endpoint の base URL を指定します: https://random-cat-fact.p.rapidapi.com。
Add endpoint をクリックします。endpoint の name を catFact、relative path を / にします。HTTP method は GET です。
Add endpoint をクリックして endpoint を保存します。

API には X-RapidAPI-Key と X-RapidAPI-Host の 2 つの header が必要です。Squid Console でこれらを API schema に追加しましょう。

Request 内の + をクリックし、X-RapidAPI-Key という name の field を追加します。field の location は HEADER です。

新しい field を追加

Request 内の + をもう一度クリックし、X-RapidAPI-Host という name の field を追加します。field の location は HEADER です。

Console の Header

これらの header を client からの call に追加する代わりに、Squid injection feature を使用して endpoint からのすべての API call に specific field を追加できます。すべての call に X-RapidAPI-Key と X-RapidAPI-Host header が必要なため、schema の Injections section に追加します。API key を安全に保つため、Squid Secretsを使用します。

Injections 内の + をクリックします。field の name を X-RapidAPI-Key にします。field の location として HEADER を選択します。
Is this a secret value? を On に toggle します。secret を選択する dropdown が表示されます。
Select secret の dropdown で Create secret をクリックします。
Secret key に catFacts2 と入力します。
secret value には、Random Cat Fact API の RapidAPI page から X-RapidAPI-Key value を copy します。これを secret の value として paste し、Save をクリックします。
inject する field を保存するには、Add field をクリックします。
Injections 内の + をもう一度クリックします。今回は field の name を X-RapidAPI-Host にします。field の location として HEADER を選択します。
field の value に random-cat-fact.p.rapidapi.com と入力して、Save をクリックします。

Console の Injection

schema に加えたすべての change を保存するには、Save schema をクリックします。
Cat Facts application の frontend で、App.tsx の現在の useEffect functionality を以下に置き換えます。

Client code
useEffect(() => {
  squid
    .api()
    .request('catFacts2', 'catFact')
    .then((data) => {
      console.log(data);
      setFact({
        fact: data.body['fact'],
        length: JSON.stringify(data.body['fact']).length,
      } as RandomFact);
    });
}, []);

Squid backend で、2 つ目の decorator を追加して API への access を authorize する functionality を追加します。

Backend code
  @secureApi('catFacts2')
  @secureApi('catFacts')
  secureCatFacts(context: ApiCallContext): boolean {
    return true;
  }

backend で squid start、frontend で npm run dev を実行して、Cat Facts app の新しい version を実行します。app は secured API endpoint から data に access しています！

これで schema injection と Squid Secrets を使用して secured API endpoint に access する方法を理解できました！Squid HTTP API integration で利用可能な functionality の詳細については、API integration の call に関する documentationを参照してください。

Squid は任意の API と統合できるため、complex migration を必要とせずに複数 data source で Squid の power を活用できます。​

TL;DR​

新しい React Project を作成する​

Console で新しい App を作成する​

API Connector を作成する​

Connector を理解する​

Security Rule​

Client で API を使用する​

Setup​

App.tsx​

Project を実行する​

次のステップ​

Bonus: HTTP Header を組み込む​