API Gateways

Your Enterprise Hub comes with a Rapid Runtime configured as the default gateway. The RapidRuntime is hosted at rapidapi.com. This means that API requests will be directed to the hosted Rapid Runtime and then forwarded to another gateway or API endpoint. This is shown in the following diagram:

If you want to publish APIs on the Enterprise Hub that do not use the hosted Rapid Runtime, you can configure one or more alternative gateways in the Admin Panel, as discussed below. API providers can then configure an API to use the new gateway for API requests. This removes the hosted Rapid Runtime from runtime requests.

If an API provider selects multiple gateways when configuring the API, or if the {{API_BASE_URL}}) is used in the code template for the gateway and multiple Base URLs are defined in the OpenAPI document, the API consumer is given a choice of which URL to use when making API requests.

📘

Explanation of the URLs in the diagrams above

[subdomains].rapidapi.com/group/endpoint - If your API uses the hosted Rapid Runtime, all API requests are initially sent to rapidapi.com. Rapid uses the subdomains in the URL to identify the API, and forwards the requests to the endpoints described below.

[base url]/group/endpoint - If your API uses the hosted Rapid Runtime, the Runtime forwards requests to a URL that contains the Base URL. API consumers never see this Base URL. The Base URL is configured for each API in the Studio (My APIs) or by using the "servers" object in an OpenAPI document. To specify the Base URL using Studio, navigate to Hub Listing > General and scroll down to enter Base URL(s).

[base url or gateway url]/group/endpoint - If your API does not use the hosted Rapid Runtime, API consumers send requests directly to the Base URL (if {{API_BASE_URL}}) is specified in the Code Template for the gateway) or Gateway URL. If the Gateway URL is specified, the Base URL described above is not used.

Managing API gateways

To not use the hosted Rapid Runtime in API requests, an Environment Admin uses the API Gateways tab of the Admin Panel to configure one or more API gateways. API providers can then select the appropriate API gateway(s) when defining the API. In the screenshot below, one hosted Rapid Runtime and three external API gateways are configured for this Enterprise Hub.

Adding API gateways

To begin adding an API gateway, click the Add Gateway button. You then enter the following information:

• Gateway DNS - This is the URL to the API gateway or to the API itself. This URL does not contain API groups or endpoints. It is similar to the Base URL that is configured for APIs that use the hosted Rapid Runtime. For example, if you add a Gateway DNS of mycompany.com/api, API requests (such as when testing an endpoint from the API Hub) will be made to mycompany.com/api rather than to [subdomains].rapidapi.com.

• Type - This can be either the Rapid Runtime or a non-Rapid API gateway. For non-Rapid API gateways, you can select any other gateway type. Since these request are not proxied by the Rapid Runtime, the traffic related configurations described below need to be made directly on those gateways.

• Code Template - The code template is used to display correct code snippets in the API Hub. This is needed because the URLs in the code snippets will now point to the API gateway (not rapidapi.com). You must have configured a code template before adding an API gateway. Please see code-templates.

• (Rapid Runtime only) Gateway Default Time-Out - If the response from any target API takes longer than this value, the Runtime will return a 504 error to the client. This value is also the maximum value that any API provider can configure for their API. See gateway timeouts to learn more.

• (Rapid Runtime only) Request Size Limit - If the size of the request from any client is larger than this value, the Runtime will return a 413 error to the client. This value is also the maximum value that any API provider can configure for their API. See request size limits to learn more.

• (Rapid Runtime only) Allow HTTP traffic through Gateway - The default is to allow only HTTPS.

• (Rapid Runtime only) Custom Error Messages - Used to customize messages for Runtime errors.

📘

Gateway status

Each API gateway configured in Rapid has a Status. While in use, the gateway's Status is set to "Active". To edit a gateway, click on the "Deactivate" link associated with the gateway (see the screenshot under Managing API Gateways above). A gateway may only be edited when it is inactive.

Managing CORS on API gateways

🚧

This section only applies to testing API endpoints and only if you are not using the hosted Rapid Runtime at all for your API. To bypass these CORS concerns while testing APIs, an API provider can include the hosted Rapid Runtime as an option for API consumers. This is described more at the end of this page.

Browsers have a security model that, by default, prevents a web page hosted at one domain (e.g. rapidapi.com) from making fetch() or XMLHttpRequest requests to a different domain (e.g. yourcompany.com).

If you are testing an API endpoint from the API Hub and using the hosted Rapid Runtime there is no security-related problem because the API Hub and the Rapid Runtime are hosted on the same domain (rapidapi.com).

When you do not use the Rapid Runtime (as described in this document), you may run into a security problem when testing the API endpoints from the API Hub. This happens when the API Hub web page and the API endpoints are on different domains.

To allow for browsers to make API calls to other domains, Cross Origin Resource Sharing (CORS) can be used. To set this up, you must configure your API gateway to return CORS headers for both the OPTIONS method and the actual endpoint method (for example, GET). The OPTIONS method is needed for preflight requests because custom headers are sent from the Enterprise Hub API playground.

The following response headers should be configured for the OPTIONS method (replace YOURSUBDOMAIN with the value from the URL of your Enterprise Hub):

"Access-Control-Allow-Headers": "cache-control,expires,pragma,usequerystring,x-rapidapi-ua,authorization"
"Access-Control-Allow-Origin": "https://[YOURSUBDOMAIN].hub.rapidapi.com"

The "authorization" header above is needed if your API includes a non-Rapid authentication set such as OAuth2 (see Configuring API Authentication).

If you are not concerned with allowing specific headers, you can specify the wildcard ("*") for the Access-Control-Allow-Headers header value:

"Access-Control-Allow-Headers": "*"
"Access-Control-Allow-Origin": "https://[YOURSUBDOMAIN].hub.rapidapi.com"

The following response header should be configured for the actual endpoint method (for example, GET).

"Access-Control-Allow-Origin": "https://[YOURSUBDOMAIN].hub.rapidapi.com"

📘

Amazon API Gateway example

See Setting up CORS on Amazon API Gateway for an example.

Please contact support at https://support.rapidapi.com/ if you require help with this topic.

Code templates

A code template defines the structure of the sample code snippet for an API when its corresponding gateway is selected. A gateway can use only one code template. Code templates are needed primarily because the URLs in the code snippets must point directly to the API gateway, rather than to the hosted Rapid Runtim.

Code templates are assigned to a gateway when the gateway is added or edited using the Admin Panel (see above). Code templates can be created and edited in the Admin Panel by selecting the API Gateways link in the sidebar and then clicking the Code Templates tab, as shown below.

Defining code templates

When creating or editing a code template, you provide the following information:

Name - Use when selecting a code template for use with a gateway.

Description - A brief description of the template.

Request URL - Specifies the URL used for requests in the code snippets. To avoid hard-coding the entire URL, parameters (surrounded by {{ and }}) can be specified in the URL. The following parameters may be used in the value of the request URL or any of the headers:

• {{API_BASE_URL}} : Uses the Base URL(s) defined in the Provider Dashboard for the API that uses this template (API's definition tab > API Specs > Settings > Base URL) or the servers object in the OpenAPI document for the API that uses this template.
• {{GW_URL}} : The Gateway DNS value for the gateway that the code template is applied to. This is only used if you are not using {{API_BASE_URL}}.
• {{PATH}} : The path of a specific endpoint.
• {{API_ID}} : The name of the API.

📘

Advantages of using {{API_BASE_URL}}

If the code template for the API gateway uses {{API_BASE_URL}}, only a single API gateway needs to be configured in the Admin Panel, and it can be used for many APIs in the Enterprise Hub. Unique URLs (and API gateways) for each API are then specified in the Base URL(s) or servers object for the API, not in the Admin Panel. If you want to send unique headers for certain types of API gateways, you may create several API Gateways in the Admin Panel - one for each set of unique headers.

Header Parameters - Specifies header name/value pairs that are added to the code snippets. For instance, if all of your APIs use the same authentication (e.g. a key or token in the header) and your OpenAPI documents do not contain the authentication information for each API, you can define a header called "Authorization" that gets applied to the code snippet for every API on this gateway. Alternatively, if your OpenAPI documents contain authentication information, you may not need to specify such a header.

As you fill in the information above, you will see a read-only code snippets preview in the language of your choice.

In the following code template, the Request URL has been set to {{API_BASE_URL}}{{PATH}}. This is a value that may work for many API gateways, since nothing is hard-coded in this URL.

Specifying the gateway(s) used for an API (API providers)

Once an API gateway has been configured in the Admin Panel, API providers can specify that their API uses the gateway. Navigate to My APIs, navigate to the API, then click Hub Listing > Gateway and select the gateway under Gateway DNS (see below). At this point, any API consumer testing the API's endpoints using the API Hub will not use the hosted Rapid Runtime, and all code snippets will use the API gateway's DNS address. If {{API_BASE_URL}}) is used in the code template for the gateway, the Base URL(s) or OpenAPI document servers object will be used to determine the URLs used to test the API and in the code snippets.

The API provider can add multiple gateways to the Gateway DNS field. If {{API_BASE_URL}}) is used in the code template for the gateway, multiple Base URL(s) or OpenAPI document servers object URLs can be used. If multiple URLs are available, the API consumer is provided a choice of which gateway (URL) to use in requests.

Specifying the gateway(s) used for an API (API consumers)

If an API provider has specified multiple gateways under Gateway DNS or if {{API_BASE_URL}}) is used in the code template for the gateway and multiple Base URLs or OpenAPI document servers are defined, the API consumer can select which URL to use when making calls to the API. To do this, the API consumer uses the Request URL dropdown in the API playground (as shown below).

📘

Using the hosted Rapid Runtime for testing endpoints

To bypass the CORS issues described above, your enterprise may want to use the hosted Rapid Runtime for testing endpoints, and not use the hosted Rapid Runtime for runtime requests. To do this, the API provider adds multiple gateways to the Gateway DNS section, including the hosted rapidapi.com Runtime. When testing the API endpoints, consumers select the rapidapi.com value from the Request URL section of the playground, as shown above. They can then select the configured (external) gateway for code snippets so that the Rapid Runtime is not used for runtime requests.