Skip to main content

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 API types can be added using HTTP API connector found in the list of available API connectors.

Benefits​

The Squid Client SDK facilitates API access and schema autodiscovery, routing API calls through Squid for enhanced security and simplifying the development process. 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 connector​

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

  • Connector ID - An ID of your choice. It is best 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. If this field is left blank, you can also opt to upload the API schema file after adding the connector.

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

Using the API connector​

Once you've created a connector, 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
);

Autodiscovery and defining the schema​

For OpenAPI specification endpoints, the Squid Console automatically discovers the schema, making the configuration process more accurate and convenient. Endpoints are automatically grouped based on tags and are searchable, making long lists of endpoints easier to work with. If the API does not use an OpenAPI spec, you can manually define the schema in the console.

API connectors 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.

Squid Console API overview

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. For each endpoint you can define the request and the response. 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). If you are including path parameters, ensure these are enclosed in brackets (e.g. /YOUR_ENDPOINT_ID/{pathParam}).

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: Editing an endpoint

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_CONNECTOR_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_CONNECTOR_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 security rules for accessing endpoints using the Squid Client SDK.

To secure an HTTP API connector, 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.