# HTTP Gateways (optional)

Table of Contents

As part of the Airnode deployment you can decide to deploy two different HTTP Gateways.

HTTP Gateway: testing
HTTP Signed Data Gateway: production use

# Gateway Differences

Both gateways are setup identically. The differences are in their purpose and response.

# HTTP Gateway

The regular HTTP gateway is strictly for testing purposes. Using a simple tool like CURL you can test that endpoints in the Airnode configuration are working properly without accessing the blockchain.

# HTTP Signed Data Gateway

The HTTP signed data gateway is used for production purposes. While it is executed in a similar way as the HTTP gateway, its response is signed and does not contain a rawValue field. This gateway is executed by an off-chain code source that may in turn push data to a blockchain.

# Setup

Enable either gateway in the config.json file fields nodeSettings.httpGateway and nodeSettings.httpSignedDataGateway.

enabled: A boolean to enable/disable for the gateway.
apiKey: A user defined API key to authenticate against the gateway. The key must have a length of between 30 - 120 characters.
maxConcurrency: (optional) A number higher than zero that represents the maximum number of serverless functions serving gateway requests. When omitted, there is no maximum concurrency set. This field is ignored for Airnode client gateways.
corsOrigins: A list of allowed origins, ['*'] to allow all origins or an empty array to disable CORS.

"nodeSettings": {
  "cloudProvider": {
    "type": "aws",
    "region": "us-east-1"
  },
  "airnodeWalletMnemonic": "${AIRNODE_WALLET_MNEMONIC}",
  "heartbeat": {...},
  "httpGateway": {
    "enabled": true,
    "apiKey": "${HTTP_GATEWAY_API_KEY}",
    "maxConcurrency": 20,
    "corsOrigins": []
  },
  "httpSignedDataGateway": {
    "enabled": true,
    "apiKey": "${HTTP_SIGNED_DATA_GATEWAY_API_KEY}",
    "maxConcurrency": 20,
    "corsOrigins": []
  },
  ...
},

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Add the desired endpoints the gateways can respond to in the triggers.http[n] and/or triggers.httpSignedData[n] arrays. The corresponding arrays do not need to match. You may want to test all endpoints but only serve certain endpoints using the HTTP signed data gateway or via RRP.

// in config.json
"triggers": {
  "rrp": [
    {
      "endpointId": "0x6db9e3e3d073ad12b66d28dd85bcf49f58577270b1cc2d48a43c7025f5c27af6",
      "oisTitle": "CoinGecko Basic Request",
      "endpointName": "coinMarketData",
      "cacheResponses": false
    }
  ],
  "http": [
    {
      "endpointId": "0x6db9e3e3d073ad12b66d28dd85bcf49f58577270b1cc2d48a43c7025f5c27af6",
      "oisTitle": "CoinGecko Basic Request",
      "endpointName": "coinMarketData",
    }
  ],
  "httpSignedData": [
    {
      "endpointId": "0x6db9e3e3d073ad12b66d28dd85bcf49f58577270b1cc2d48a43c7025f5c27af6",
      "oisTitle": "CoinGecko Basic Request",
      "endpointName": "coinMarketData",
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# Gateway URLs

The gateway implementation is different depending on how Airnode is deployed. When deployed on a cloud provider, the serverless gateway is used. Inside Airnode client, the gateway is implemented via a simple web server inside the docker container. There are subtle differences in both how the gateways work and how do the gateway URLs look like.

The gateway URLs are also available as part of the payload sent from Airnode's heartbeat to your specified heartbeat URL.

# When deployed on a cloud provider

A gateway URL is generated for each gateway (when enabled) when Airnode is deployed. You can see the URLs displayed on your terminal at the end of an Airnode deployment using a Docker image.

# When using Airnode client

Airnode client can be used to run Airnode as a docker container locally. There is a common web server for both gateways, which is exposed on the host machine. Doing so will make the gateways API accessible like a regular web server running on the machine. Each gateway has a separate endpoint as shown below. Note the PORT which is exposed as part of the Airnode client container. See the Airnode client usage for more details.

http://localhost:<PORT>/http-data/<endpointId> - Gateway URL for the HTTP Gateway
http://localhost:<PORT>/http-signed-data/<endpointId> - Gateway URL for the HTTP Signed Data Gateway

# Using CURL

In order to execute an endpoint served by either gateway, the following are required as part of the CURL call.

Make a POST request with the endpointId as a path parameter. An endpointId can found in config.json under triggers.http.endpointId or triggers.httpSignedData.endpointId.
Add the Content-Type header, set to application/json.
Add the x-api-key header, set to the apiKey. The x-api-key can found in config.json under nodeSettings.httpGateway.apiKey or nodeSettings.httpSignedDataGateway.apiKey.
Place the parameters/encodedParameters in the request body.

CURL Parameters	In	CURL Options
Content-Type	header	`-H 'Content-Type: application/json'`
x-api-key	header	`-H 'x-api-key: 8d890a46-799d-48b3-a337-8531e23dfe8e'`
endpointId	path	`<gatewayUrl>/0x6db9e3e3d0...c7025f5c27af6`
* parameters HTTP Gateway	body	`-d '{"parameters": {"param1": "myValue", "param2": 5}}'`
* encodedParameters HTTP Signed Data Gateway	body	`-d '{"encodedParameters": "0x3173737300....000"}'`

* Parameters for the gateways are named differently. The HTTP signed data gateway requires that the encodedParameters be encoded using Airnode ABI.

Replace <gatewayUrl> in the examples below with the URL displayed in the terminal at the end of an Airnode deployment using a Docker image.

# Request

# Response

# Tutorials

The airnode-examples monorepo hosts examples demonstrating use of the HTTP Gateway and HTTP Signed Data Gateway, see here. Furthermore, there are additional examples of using CURL to call the HTTP gateway in both the Quick Deploy AWS and Quick Deploy GCP tutorials.

← Heartbeat Deploying Airnode →