Calling your API integration

By integrating your APIs with Squid, you can take advantage of highly configurable security in the backend and intuitive functionality with the Squid Client SDK

Squid lets you connect and secure any API for streamlined access from client applications. Use the Squid Backend SDK to manage API role-based access and permissions, and then call the API from a client using the Squid Client SDK.

To access your external API integrations with Squid, first connect the API by adding it as an integration. To learn how to connect an API and manage your API schema, view the API integration documentation.

Invoking the API

To invoke your API integration, use the squid.api().request() method, passing the integration ID and endpoint ID of your integration:

Client code

const result = await squid
  .api()
  .request('YOUR_INTEGRATION_ID', 'YOUR_ENDPOINT_ID');

Optional Parameters

Squid API calls have three optional parameters: body, options, and method.

body

The body is an optional parameter for the data sent by the client to your API. It takes whatever format is required by the API and is optional to acommodate requests that don't take a body, like GET requests.

The following example shows a request with a body parameter in JSON format:

Client code

const result = await squid.api().request(
  'YOUR_INTEGRATION_ID',
  'YOUR_ENDPOINT_ID',
  { user_name: 'newUser1' } // the body of the request
);

options

The options is an optional parameter to use when including headers, query parameters, or path parameters for the request:

export interface ApiOptions {
  headers?: Record<string, string | number | boolean>;
  queryParams?: Record<string, string | number | boolean>;
  pathParams?: Record<string, string | number | boolean>;
}

The following example shows the format of a request with body and options parameters:

Client code

const result = await squid.api().request(
  'YOUR_INTEGRATION_ID',
  'YOUR_ENDPOINT_ID',
  { user_name: 'newUser1' },
  {
    headers: { api_key: YOUR_API_KEY },
    queryParams: { new_user: true },
    pathParams: { 'subscriber-group': 42 },
  }
);

method

The method is an optional parameter indicating the type of request. If no method is specified, then the default method as defined in the integration is used. To find the default method of the integration, select the API integration from the integration page of the Squid Console. The following methods are available:

• 'post'
• 'get'
• 'delete'
• 'patch'
• 'put'

This example shows a 'post' API request:

Client code

const result = await squid.api().request(
  'YOUR_INTEGRATION_ID',
  'YOUR_ENDPOINT_ID',
  { user_name: 'newUser1' },
  {
    headers: { api_key: YOUR_API_KEY },
    queryParams: { new_user: true },
    pathParams: { 'subscriber-group': 42 },
  },
  'post'
);

When this example function is called, Squid performs the following HTTP request:

POST /subscriber-group/42?new_user=true
{
  "user_name": "newUser1"
}

Note

When making an API request from the Squid backend, access the built-in Squid client instance using this.squid:

Backend code

const result = await this.squid.api().request(
  'YOUR_INTEGRATION_ID',
  'YOUR_ENDPOINT_ID',
  { user_name: 'newUser1 ' },
  {
    headers: { api_key: YOUR_API_KEY },
    queryParams: { new_user: true },
    pathParams: { 'subscriber-group': 42 },
  },
  'post'
);

Helper methods

In addition to the generic request method, Squid provides helper methods for each type of request. These methods have the same functionality as calling request with the desired method parameter; they just help streamline authoring and readability of code.

The following helper methods are available:

get

When making a get request to your API, you can use the squid.api().get() method, passing your integration ID, endpoint ID, and any options. The format of the options parameter is the same as the request method.

Client code

squid.api().get('YOUR_INTEGRATION_ID', 'YOUR_ENDPOINT_ID', options);

post

When making a post request to your API, you can use the squid.api().post() method, passing your integration ID, endpoint ID, an optional body, and any options. The format of the body and options parameters are the same as the request method.

Client code

squid.api().post('YOUR_INTEGRATION_ID', 'YOUR_ENDPOINT_ID', body, options);

delete

When making a delete request to your API, you can use the squid.api().delete() method, passing your integration ID, endpoint ID, an optional body, and any options. The format of the body and options parameters are the same as the request method.

Client code

squid.api().delete('YOUR_INTEGRATION_ID', 'YOUR_ENDPOINT_ID', body, options);

patch

When making a patch request to your API, you can use the squid.api().patch() method, passing your integration ID, endpoint ID, an optional body, and any options. The format of the body and options parameters are the same as the request method.

Client code

squid.api().patch(integrationId, endpointId, body, options);

put

When making a put request to your API, you can use the squid.api().put() method, passing your integration ID, endpoint ID, an optional body, and any options. The format of the body and options parameters are the same as the request method.

Client code

squid.api().put('YOUR_INTEGRATION_ID', 'YOUR_ENDPOINT_ID', body, options);

Return value

All squid.api() methods return a Promise with an object of type: HttpResponse<T>.

T is the type of the expected body:

export interface HttpResponse<T = unknown> {
  status: number;
  statusText: string;
  headers: Record<string, string>;
  body: T;
}

Handling errors

In case of an HTTP error or any other error, an RpcError is thrown with all the raw data returned by the endpoint.