Chapter 3. Advanced APIcast configuration
Chapter 3. Advanced APIcast configuration This section covers the advanced settings option of the 3scale 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 Note There are field restrictions of maximum length and reserved characters for the user_keys field: Allowed characters [A-Z a-z 0-9 - _ .] , or Base64 format without a forward slash (/), no spaces and up to 256 characters. There are field restrictions of maximum length and reserved characters for the application_id field, which is known as the app_id or client_id field: Allowed characters: [A-Z a-z 0-9 ! " # USD % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~] , no spaces and between 5 and 255 characters. There are field restrictions of maximum length and reserved characters for the app_key , and client_secret fields: Allowed characters: [A-Z a-z 0-9 ! " # USD % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~] , no spaces and between 5 and 255 characters. 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 HTTP Basic Auth format or as query parameters (GET), or body parameters (POST/PUT/DELETE). Note 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 or 400 Bad Request , APIcast returns the message to the client. However, if APIcast detects other errors such as Authentication 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 configuration files: Navigate from [Your_product_name] > Integration > Configuration . Click the Configuration history link, located to the environment of your interest: Staging APIcast or Production APIcast . Note that it is not possible to automatically roll back to 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 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, for example, 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: api.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.example2.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.
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