Call a REST API through the gateway
A REST API route puts the gateway in front of an HTTP API. You call the gateway’s URL instead of the API’s, and the gateway checks your access, applies the route’s plugins, and forwards the request. Apart from the URL and the gateway key, you call the API the same way you would call it directly. This topic shows you how to build the URL, send a request, and what the gateway changes and doesn’t change.
Prerequisites
Before you begin, make sure you have the following:
- A REST API route. Your admin creates it, for example by importing an OpenAPI spec. For details, see Connect a REST API.
- A gateway key for the route, if the route requires one. Ask your admin.
- cURL, Postman, or any HTTP client.
Build the URL
The URL is the data plane host followed by the route’s path, for example https://GATEWAY_HOST/petstore/pets/42. To copy the base URL, in the console sidebar, select Services, select the Routes tab, find the route, and then select the Copy DP URL icon in its row.
If your admin imported the API with a Route prefix, the prefix is part of the gateway URL, and the gateway strips it before it forwards the request. For example, with the prefix /petstore, a request to https://GATEWAY_HOST/petstore/pets/42 reaches the API as /pets/42. Query strings pass through unchanged.
Paths match exactly, with letter case. One trailing slash is ignored when the gateway matches the route, but the API still receives the slash that you sent.
Send a request
Send your gateway key in the fg-api-key header. Replace GATEWAY_HOST and GATEWAY_KEY:
A successful request returns the API’s own status, headers, and body, plus an X-Request-Id header that identifies the request in the gateway’s traces.
Because the gateway key has its own header, you can still send the API’s own headers, such as Authorization. The gateway passes them through. Whether you need to send the API’s credentials depends on the connection: if your admin added an upstream credential to it, the gateway adds that credential for you. Otherwise, send your own.
Understand what the gateway changes
On the way to the API, the gateway does the following:
On the way back, you get the API’s status, headers, and body unchanged, unless a response plugin on the route transforms them. Streamed responses, such as server-sent events, are passed on event by event as they arrive.
The gateway doesn’t support the following:
- WebSocket. The
Upgradeheader is removed, so a WebSocket handshake can’t complete through the gateway. - CORS. The gateway doesn’t answer browser preflight requests or add
Access-Control-*headers. A browser app can’t call a route that requires a gateway key unless something in front of the gateway answers the preflight.
Verify the request
Check the response:
For the full list, see Handle errors and retries.
Next steps
- To learn which errors are safe to retry, see Handle errors and retries.
- To see each step a request goes through, see Follow a request through the gateway.
- To find your request in the gateway’s records, see Inspect traces.

