Skip to navigation

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:

curl -i "https://GATEWAY_HOST/petstore/pets/42" \
-H "fg-api-key: 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:

WhatBehavior
Gateway keyRemoved. The API never sees your fg-api-key value.
Upstream credentialAdded, if the connection has one.
PathRoute prefix or path rewrite applied. Dot segments such as /../ are resolved and repeated slashes collapsed before matching, and the API receives the cleaned path.
HostSet to the API’s host.
X-Forwarded-For, X-Forwarded-Host, X-Forwarded-ProtoAdded or extended, so the API can see where the request came from.
X-Request-IdKept if you sent one of up to 256 characters, otherwise generated. The same value is sent to the API and returned to you.
Hop-by-hop headersConnection, Keep-Alive, Proxy-Authenticate, Proxy-Authorization, TE, Trailer, Transfer-Encoding, and Upgrade are removed.
Query string and bodyUnchanged, unless a plugin on the route transforms them.

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 Upgrade header 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:

What you seeWhat it means
The API’s normal responseThe request went through.
404 with the body 404 page not foundNo route matches the path. Check the URL and the route prefix.
405 with an Allow headerThe route exists, but not for this method. Allow lists the methods it accepts.
401 with the body UnauthorizedThe gateway key is missing or wrong.
502 or 503The gateway couldn’t reach the API, or no healthy upstream was available.

For the full list, see Handle errors and retries.

Next steps