Chapter 1. Introduction to advanced operation of 3scale API Management APIcast API gateway

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.

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"

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"

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"

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.

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:

View larger image

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:

View larger image

Mapping rules work at the API product and API backend levels.

Now consider an additional product called Tools For Devs using the same Echo API backend.

(get) /path/to/example/search
(get) /path/to/example/{id}

(get) /path/to/example/search
(get) /path/to/example/{id}

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.

There are special cases that require custom APIcast configuration so that API consumers can successfully call the API.

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.

View larger image