Cloud-native API Administration with Red Hat 3scale API Management

The design of the public-facing API must accept a version number in the URL path. Doing so ensures that client applications of the API supply the URL version during development.

For example, clients for the first API version use a URL such as https://example.com/v1/resource-name, where the v1 indicates the version of the API the client wants to consume.

To release a breaking change, you must change the URL to use a new version.

Following the previous example, incrementing from v1 to v2 changes the URL to https://example.com/v2/resource-name, representing the new version.

The different versions in the request path route the request to the correct endpoint in the target API.

For URL versioning, create a backend for each of the versions and set the private base URL of the backend to point to the desired API version.

Having each backend point to a different path creates a logical separation for each version.

For the preceding example, you assign both backends to the product by using a public path that represents the version.

For example, the public path for backend version v2 is /v2.

When handling the request, 3scale API Management rewrites the path and eliminates the public path specified in the mapping between the product and the backend.

To implement request header versioning, use the Routing policy.

This policy routes requests based on the URL, request headers, or JWT claims.

The Routing policy must be placed before the APIcast policy in the policy chain.

Figure 2.17: Product policies

You can configure the Routing policy to route requests by using a custom header, such as x-api-version.

For this, you can configure the Routing policy in the Admin Portal with the following values.

With this configuration, the Routing policy routes requests containing the header x-api-version: v2 to http://microservice-interal-url/api/v2.

After updating the policy configuration, you must click Update Policy Chain in the Policies section. Then, promote the configuration to staging to verify that it routes to the correct version.

You can use the curl utility to test the request header versioning by adding the version header to the request.

[student@workstation ~]$ curl -v -s --header "x-api-version: v2" \
  "https://example.com/resource?user_key=USER_KEY"
...output omitted...
> GET /resource?user_key=b2c9a5d6204ff848052dd4ba6944fbc7 HTTP/1.1
> Host: example.com
> User-Agent: curl/7.61.1
> Accept: /
> x-api-version: v2
>
...output omitted...
< HTTP/1.1 200 OK
...output omitted...

You can also use the 3scale Toolbox CLI to create the policy chain by executing the policies command with the import subcommand and an argument with a file containing the policy list.

[student@workstation ~]$ 3scale policies import \
  TENANT PRODUCT -f policy-chain.yaml

Where policy-chain.yaml contains a policy list with the Routing policy followed by the default 3scale APIcast policy.

- name: routing
  version: builtin
  configuration:
    rules:
    - condition:
        combine_op: and
        operations:
        - value_type: plain
          match: header
          value: v2
          op: matches
          header_name: x-api-version
      url: http://example.com/api/v2
  enabled: true
- name: apicast
  version: builtin
  configuration: {}
  enabled: true

This command creates a new configuration for the product and promotes that configuration to the staging environment.