Chapter 1. Introduction to advanced operation of 3scale API Management APIcast API gateway The introduction to advanced operation of 3scale APIcast will help you to adjust the configuration of access to your application programming interface (API). 1.1. Public base URL for calls to 3scale API Management APIs The Public Base URL is the URL that your API consumers use to make requests to your API product, which is exposed publicly with 3scale. This will be the URL of your APIcast instance. If you are using one of the Self-managed deployment options , you can choose your own Public Base URL for each of the environments provided (staging and production) on a domain name you are managing. This URL should be different from the one for your API backend, and could be something like https://api.yourdomain.com:443 , where yourdomain.com is the domain that belongs to you. After setting the Public Base URL, make sure you save the changes and, if necessary, promote the changes in staging to production. Note The Public Base URL that you specify must use a port that is available in your OpenShift cluster. By default, the OpenShift router listens for connections only on the standard HTTP and HTTPS ports (80 and 443). If you want users to connect to your API over some other port, work with your OpenShift administrator to enable the port. APIcast accepts calls to only the hostname specified in the Public Base URL. For example, if you specify https://echo-api.3scale.net:443 as the Public Base URL, the correct call would be: curl "https://echo-api.3scale.net:443/hello?user_key=you_user_key" In case you do not have a public domain for your API, you can use the APIcast IP address in the requests, but you still need to specify a value in the Public Base URL field even if the domain is not real. In this case, make sure you provide the host in the Host header. For example: curl "http://192.0.2.12:80/hello?user_key=your_user_key" -H "Host: echo-api.3scale.net" If you are deploying on a local machine, you can specify "localhost" as the domain, so the Public Base URL would look like http://localhost:80 , and then you can make requests like this: curl "http://localhost:80/hello?user_key=your_user_key" If you have multiple API products, set the Public Base URL appropriately for each product. APIcast routes the requests based on the hostname. 1.2. How APIcast applies mapping rules for capturing usage of 3scale API Management APIs Based on the requests to your API, mapping rules define the metrics or designate the methods for which you want to capture API usage. The following is an example of a mapping rule: This rule means that any GET requests that start with / increment the metric hits by 1. This rule matches any request to your API. While this is a valid mapping rule, it is too generic and often leads to double counts if you add more specific mapping rules. The following mapping rules for the Echo API show more specific examples: Mapping rules work at the API product and API backend levels. Mapping rules at the product level. The mapping rule takes precedence. This means that the product mapping rule is the first one to be evaluated. The mapping rule is always evaluated, independent of which backend receives the redirected traffic. Mapping rules at the backend level. When you add mapping rules to a backend, these are added to all the products bundling said backend. The mapping rule is evaluated after the mapping rules defined at the product level. The mapping rule is evaluated only if the traffic is redirected to the same backend the mapping rule belongs to. The path of the backend for a product is automatically prepended to each mapping rule of the backend bundled to said product. Example of mapping rules with products and backends The following example shows mapping rules for a product with one backend. The Echo API backend: Has the private endpoint: https://echo-api.3scale.net Contains 2 mapping rules with the following patterns: The Cool API product: Has this public endpoint: https://cool.api Uses the Echo API backend with this routing path: /echo . Mapping rules with the following patterns are automatically part of the Cool API product: This means that a request sent to the public URL https://cool.api/echo/hello is redirected to https://echo-api.3scale.net/hello . Similarly, a request sent to https://cool.api/echo/bye redirects to https://echo-api.3scale.net/bye . Now consider an additional product called Tools For Devs using the same Echo API backend. The Tools For Devs product: Has this public endpoint: https://dev-tools.api Uses the Echo API backend with the following routing path: /tellmeback . Mapping rules with the following patterns are automatically part of the Tools For Devs product: Therefore, a request sent to the public URL https://dev-tools.api/tellmeback/hello is redirected to https://echo-api.3scale.net/hello . Similarly, a request sent to https://dev-tools.api/tellmeback/bye redirects to https://echo-api.3scale.net/bye . If you add a mapping rule with the /ping pattern to the Echo API backend, both products - Cool API and Tools For Devs - are affected: Cool API has a mapping rule with this pattern: /echo/ping . Tools For Devs has a mapping rule with this pattern: /tellmeback/ping . Matching of mapping rules 3scale applies mapping rules based on prefixes. The notation follows the OpenAPI and ActiveDocs specifications: A mapping rule must start with a forward slash ( / ). Perform a match on the path over a literal string, which is a URL, for example, /hello . The mapping rule, once you have saved it, will cause requests to the URL string you have set and invoke metrics or methods you have defined around each mapping rule. Mapping rules can include parameters on the query string or in the body, for example, /{word}?value={value} ). APIcast fetches the parameters in the following ways: GET method: From the query string. POST , DELETE , or PUT method: From the body. Mapping rules can contain named wildcards, for example, /{word} . This rule matches anything in the placeholder {word} , which makes requests such as /morning match the mapping rule. Wildcards can appear between slashes or between a slash and a dot. Parameters can also include wildcards. By default, all mapping rules are evaluated from first to last, according to the sort order you specified. If you add a rule /v1 , it matches requests whose paths start with /v1 , for example, /v1/word or /v1/sentence . You can add a dollar sign ( USD ) to the end of a pattern to specify exact matching. For example, /v1/word matches only /v1/word requests, and does not match /v1/word/hello requests. For exact matching, you must also ensure that the default mapping rule that matches everything ( / ) has been disabled. More than one mapping rule can match the request path, but if none matches, the request is discarded with an HTTP 404 status code. Mapping rules workflow Mapping rules have the following workflow: You can define a new mapping rule at any time. See Defining mapping rules . Mapping rules are grayed out on the reload to prevent accidental modifications. To edit an existing mapping rule, you must enable it first by clicking the pencil icon on the right. To delete a rule, click the trash icon. All modifications and deletions are saved when you promote the changes in Integration > Configuration . Stop other mapping rules To stop processing further mapping rules, select the option Last? when you create a new mapping rule, especially after processing one or more mapping rules. For example, if you have defined multiple mapping rules associated with different metrics in the API Integration Settings , such as: The rule /path/to/example/search can be marked Last? , then when calling (get) /path/to/example/search , after matching this rule, APIcast stops processing and will not search for matches in the remaining rules, and the metric for the rule (get) /path/to/example/{id} will not be incremented. 1.3. How APIcast handles APIs that have custom requirements There are special cases that require custom APIcast configuration so that API consumers can successfully call the API. Host header This option is only needed for those API products that reject traffic unless the Host header matches the expected one. In these cases, having a gateway in front of your API product causes problems because the Host is the one of the gateway, for example, xxx-yyy.staging.apicast.io . To avoid this issue, you can define the host your API product expects in the Host Header field in the Authentication Settings : [Your_product_name] > Integration > Settings . The result is that the hosted APIcast instance rewrites the host specification in the request call. Protecting your API backend After you have APIcast working in production, you might want to restrict direct access to your API product to only those calls that specify a secret token that you specify. Do this by setting the APIcast Secret Token . See Advanced APIcast configuration for information on how to set it up. Using APIcast with private APIs With APIcast, it is possible to protect the APIs that are not publicly accessible on the internet. The requirements that must be met are: Self-managed APIcast must be used as the deployment option. APIcast needs to be accessible from the public internet and be able to make outbound calls to the 3scale Service Management API. The API product should be accessible by APIcast. In this case, you can set your internal domain name or the IP address of your API in the Private Base URL field and follow the rest of the steps as usual. However, doing this means that you cannot take advantage of the staging environment. Test calls will not be successful because the staging APIcast instance is hosted by 3scale, which does not have access to your private API backend. After you deploy APIcast in your production environment, if the configuration is correct, APIcast works as expected.

Commands:
curl "https://echo-api.3scale.net:443/hello?user_key=you_user_key"
curl "http://192.0.2.12:80/hello?user_key=your_user_key" -H "Host: echo-api.3scale.net"
curl "http://localhost:80/hello?user_key=your_user_key"
/hello /bye
/echo/hello /echo/bye
/tellmeback/hello /tellmeback/bye
(get) /path/to/example/search (get) /path/to/example/{id}