Chapter 3. Advanced APIcast configuration
This section covers the advanced settings option of 3scale’s API gateway in the staging environment.
3.1. Define a secret token
For security reasons, any request from the 3scale gateway to your API backend contains a header called X-3scale-proxy-secret-token
. You can set the value of this header in Authentication Settings on the Integration page.
Setting the secret token acts as a shared secret between the proxy and your API so that you can block all API requests that do not come from the gateway if you do not want them to. This adds an extra layer of security to protect your public endpoint while you are in the process of setting up your traffic management policies with the sandbox gateway.
Your API backend must have a public resolvable domain for the gateway to work, so anyone who knows your API backend can bypass the credentials checking. This should not be a problem because the API gateway in the staging environment is not meant for production use, but it is always better to have a fence available.
3.2. Credentials
The API credentials within 3scale are either user_key
or app_id/app_key
depending on the authentication mode that you are using. OpenID Connect is valid for the API gateway in the staging environment, but it cannot be tested in the Integration page.
However, you might want to use different credential names in your API. In this case, you need to set custom names for the user_key
if you are using the API key mode:
Alternatively, for the app_id
and app_key
:
For instance, you could rename app_id
to key
if that fits your API better. The gateway will take the name key
and convert it to app_id
before doing the authorization call to the 3scale backend. Note that the new credential name has to be alphanumeric.
You can decide if your API passes credentials in the query string (or body if not a GET) or in the headers.
APIcast normalizes header names when extracting credentials. This means they are case insensitive, and underscores and hyphens are treated equally. For example, if you set the App Key parameter as App_Key
, other values such as app-key
are also accepted as valid app key headers.
3.3. Configuring error messages
This section describes how to configure APIcast error messages.
As a proxy, 3scale APIcast manages requests in the following ways:
- If there are no errors, APIcast passes the request from the client to the API back end server, and returns the API response to the client without modifications. In case you want to modify the responses, you can use the Header Modification policy.
-
If the API responds with an error message, such as
404 Not Found
or400 Bad Request
, APIcast returns the message to the client. However, if APIcast detects other errors such asAuthentication missing
, APIcast sends an error message and terminates the request.
Hence, you can configure these error messages to be returned by APIcast:
-
Authentication failed: This error means that the API request does not contain the valid credentials, whether due to fake credentials or because the application is temporarily suspended. Additionally, this error is generated when the metric is disabled, meaning its value is
0
. - Authentication missing: This error is generated whenever an API request does not contain any credentials. It occurs when users do not add their credentials to an API request.
- No match: This error means that the request did not match any mapping rule and therefore no metric is updated. This is not necessarily an error, but it means that either the user is trying random paths or that your mapping rules do not cover legitimate cases.
- Usage limit exceeded: This error means that the client reached its rate limits for the requested endpoint. A client may reach more than one rate limit if the request matches multiple mapping rules.
To configure errors, follow these steps:
- Navigate from [Your_product_name] > Integration > Settings.
- Under Gateway response, choose the error type you want to configure.
Specify values for these fields:
- Response Code: The three-digit HTTP response code.
-
Content-type: The value of the
Content-Type
header. - Response Body: The value of the response message body.
- To save your changes, click Update Product.
3.4. Configuration history
Every time you click Promote v.[n] to Staging APIcast, where [n] represents the version number, the current configuration is saved in a JSON file. The staging gateway will pull the latest configuration with each new request. For each environment, staging or production, you can see a history of all the previous configuration files:
- Navigate from [Your_product_name] > Integration > Configuration.
- Click the Configuration history link, located next to the environment of your interest: Staging APIcast or Production APIcast.
Note that it is not possible to automatically roll back to previous versions. Instead, you access to a history of all your configuration versions with their associated JSON files. Use these files to check what configuration you had deployed at any point of time. If you want to, you can recreate any deployments manually.
3.5. Debugging
Setting up the gateway configuration is easy, but you may still encounter errors. In such cases, the gateway can return useful debug information to track the error.
To get the debugging information from APIcast, you must add the following header to the API request: X-3scale-debug: {SERVICE_TOKEN}
with the service token corresponding to the API service that you are reaching to.
When the header is found and the service token is valid, the gateway will add the following information to the response headers:
X-3scale-matched-rules: /v1/word/{word}.json, /v1 X-3scale-credentials: app_key=APP_KEY&app_id=APP_ID X-3scale-usage: usage%5Bversion_1%5D=1&usage%5Bword%5D=1
X-3scale-matched-rules
indicates which mapping rules have been matched for the request in a comma-separated list.
The header X-3scale-credentials
returns the credentials that were passed to 3scale backend.
X-3scale-usage
indicates the usage that was reported to 3scale backend. usage%5Bversion_1%5D=1&usage%5Bword%5D=1
is a URL-encoded usage[version_1]=1&usage[word]=1
and shows that the API request incremented the methods (metrics) version_1
and word
by 1 hit each.
3.6. Path routing
APIcast handles all the API services configured on a 3scale account (or a subset of services, if the APICAST_SERVICES_LIST
environment variable is configured). Normally, APIcast routes the API requests to the appropriate API service based on the hostname of the request, by matching it with the Public Base URL. The first service where the match is found is used for the authorization.
The Path routing feature allows using the same Public Base URL on multiple services and routes the requests using the path of the request. To enable the feature, set the APICAST_PATH_ROUTING
environment variable to true
or 1
. When enabled, APIcast will map the incoming requests to the services based on both hostname and path.
This feature can be used if you want to expose multiple backend services hosted on different domains through one gateway using the same Public Base URL. To achieve this you can configure several API services for each API backend (i.e. Private Base URL) and enable the path routing feature.
For example, you have 3 services configured in the following way:
-
Service A Public Base URL:
api.example.com
Mapping rule:/a
-
Service B Public Base URL:
api2.example.com
Mapping rule:/b
-
Service C Public Base URL:
api.example.com
Mapping rule:/c
If path routing is disabled (APICAST_PATH_ROUTING=false
), all calls to api.example.com
will try to match Service A. So, the calls api.example.com/c
and api.example.com/b
will fail with a "No Mapping Rule matched" error.
If path routing is enabled (APICAST_PATH_ROUTING=true
), the calls will be matched by both host and path. So:
-
api.example.com/a
will be routed to Service A -
api.example.com/c
will be routed to Service C -
api.example.com/b
will fail with "No Mapping Rule matched" error, i.e. it will NOT match Service B, as the Public Base URL does not match.
If path routing is used, you must ensure there is no conflict between the mapping rules in different services that use the same Public Base URL, i.e. each combination of method + path pattern is only used in one service.