HTTP API

You can connect Squid to any HTTP API and map the requests and responses, enabling you to access it using the Squid Client SDK.

Squid supports two types of HTTP APIs:

1. REST APIs - APIs that use the HTTP protocol to perform CRUD operations
2. OpenAPI APIs - APIs that use the OpenAPI specification to define the API

Both integration types can be added using HTTP API integration found in the list of available API integrations.

Benefits

The Squid API integration grants clients the ability to access APIs that are typically inaccessible from the client-side because of strict security or IP limitations. The Squid Client SDK facilitates API access, which routes API calls through the Squid for enhanced security. To ensure that API access is reserved for authorized clients only, security rules can be applied to individual endpoints.

Additionally, this setup enables the secure injection of sensitive information, like authentication secrets, into API requests. Squid keeps these secrets hidden from the clients making the requests, ensuring the API's integrity and bolstering security.

Use cases

• Accessing APIs restricted from client-side access.
• Accessing APIs with IP-based access restrictions.
• Injecting secrets into the request to authenticate the client with the API.
• Providing security rules for each endpoint, ensuring that only authorized clients can access the API.

Create an HTTP API integration

To create an HTTP integration, you will need to provide the following information:

• Integration ID - You can select an ID of your choice, but it's better to keep it brief and meaningful
• OpenAPI specification URL - The URL of the OpenAPI specification file, typically ending in .yaml or .json. This is only required when connecting to an OpenAPI API.

Once you've entered the connection information, click the Next button to continue.

OpenAPI specification support

Squid facilitates the integration of OpenAPI specifications for a simplified API schema setup. When registering a new API, provide a URL to the OpenAPI specification, and Squid will parse this to automatically populate the corresponding fields in the API schema, making the configuration process more accurate and convenient.

Discovering and defining the schema

For OpenAPI specification endpoints, the Squid Console automatically discovers the schema. If the API does not use an OpenAPI spec, you can manually define the schema in the console.

Once you have defined the schema, you can use the Squid Client SDK to navigate the API and add configuration.

Endpoints

Every HTTP API integration consists of one or more endpoints. Each endpoint has a unique ID. For each endpoint you can define the request and the response. This definition is used by the Squid Client SDK when sending a request and receiving a response.

Using the Squid Client SDK

Once you've created an integration, use the Squid Client SDK to access the HTTP API. The following example shows a POST request with additional options:

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
);

To learn about using the Squid Client SDK api() methods, view the documentation on calling your APIs.

API integration schema

API integrations in Squid require the creation of a schema that outlines the necessary details for encoding and decoding requests and responses through the Squid Client SDK. This schema is essential in establishing a functional connection between Squid and RESTful APIs.

A schema consists of the following elements:

Base URL:

The base URL to which endpoint paths will be appended.

Endpoints:

A collection of different access points within the API. Each endpoint includes the following definitions:

Name:

A unique identifier for the endpoint.

Relative path:

The pathway appended to the base URL to form the complete endpoint URL (it can also include query part of a request URL).

HTTP method:

Specifies the HTTP method (e.g. GET, POST) to be used by default for the API calls.

Request description:

Comprises fields that detail the API request elements.

Response description:

Comprises fields that detail the API responses.

The following shows editing an endpoint in the Squid Console:

Injections

Injections are a feature in Squid that facilitate the insertion of predefined values into each API request, enhancing flexibility and security in API interactions. This feature can be configured in the Squid Console globally at the API schema level or individually for each endpoint.

To set up an injection, configure the following elements:

Field name:

Specifies the name of the field where the value will be injected.

Location:

Determines where the value will be placed within the request, currently supporting two options: HEADER and QUERY.

Field value:

The actual value to be injected into the specified field. This can be a direct value or retrieved from a pre-configured Squid secret.

Secret

An optional toggle to indicate that the value of the injection field is a secret and should be stored as a Squid Secret.

Consider an endpoint labeled YOUR_INTEGRATION_ID with a relative path of /YOUR_ENDPOINT_ID?someVar={mySecret} and employing the POST method. In this setup, there is one injection field configured named mySecret, with its location set to PATH and pointing to an existing Squid secret with a stored value of my-secret-value

The following example shows how to call this API from the Squid Client SDK:

Client code

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

As a result, Squid performs the following HTTP request:

POST /YOUR_ENDPOINT_ID?someVar=my-secret-value

Security rules requirements

You have the option to specify whether the integration requires security rules for accessing the different endpoints using the Squid Client SDK. By default, security rules are required, and in a production environment, it's essential to never allow access to the integration without them.

During the development or experimentation phase, you can enable access to the integration without implementing security rules. To do this, simply toggle the "Require security rules" switch, removing the need for security rule

To secure an HTTP API integration, refer to the Secure API section.

Tutorial

To see a complete example integrating an external HTTP API with Squid, check out our Cat Facts API Tutorial.