Configure REST API routing based on version query string

Host different API versions on a single base path in API Manager and distinguish between them using a query string parameter.

3 minute read

API routing based on query string version enables you to host different API versions on a single base path in API Manager and to distinguish between them using a query string parameter. For example, instead of hosting your APIs on https://HOSTNAME:8065/api/service/v1 and https://HOSTNAME:8065/api/service/v2, you can host them on a single base path of https://HOSTNAME:8065/api/service.

Then at runtime, you can specify the required API version in the URL as a query string parameter, for example:

https://HOSTNAME:8065/api/helloworld?v=v1

Example API version-based routing scenario

In this example scenario, you have a back-end service with two versions of a simple Greeting API:

  • Greeting API v1: This includes a single GET method named greet with username as header parameter, which returns a hello from v1 <username> string. For example:

    GET http:///HOSTNAME:18080/api/v1/greet
    
  • Greeting API v2: This also includes a single GET method named greet with username as a query string parameter (instead of the header parameter in Greeting API v1), and which returns a hello from v2 <username> string. For example:

    GET http:///HOSTNAME:18080/api/v2/greet
    

When you import these back-end APIs into API Manager and configure API routing based on a query string version parameter, you can host both APIs on a single base path (for example, https:///HOSTNAME:8065/api) instead of specifying the version in each path. You can then distinguish between different versions using a query string parameter in the URL (for example, https://HOSTNAME:8065/api/greet?v=v1).

Configure API version-based routing in API Manager

This section explains how to enable API routing based on a query string version parameter in API Manager. It assumes that you have already imported example back-end APIs and virtualized them as front-end APIs.

Perform the following steps in API Manager:

  1. Ensure that you are logged into API Manager as an API administrator, and that the organization is enabled for API development.

  2. Select Settings > API Manager Settings > General settings > Enable query string version routing. This setting enables multiple front-end APIs on the same base path to be differentiated by a query string version parameter, which you must enter in the next field.

  3. In the Query string version parameter field, enter the required name of the query string parameter used for routing based on version (for example, v or version). For example: API routing query string version settings

  4. When query string-based version routing has been enabled, the Query string version routing setting is displayed when you select APIFrontend API, and view the Inbound tab for a selected API.

  5. For each front-end API:

    1. Remove the version from the Resource path if necessary. For example, for Greeting API v1, you would change the default path from api/v1 to api, and for Greeting API v2, change the path from api/v2 to api.
    2. Enter the API version in the Query string version routing field instead (for example, v1 or v2 as appropriate). You can enter any value based your chosen versioning system (for example, major or minor version, with or without the prefix v).
    3. Click Save. The example following shows the front-end Greeting API v1: Frontend API routing based on query string version parameter
  6. You can use a client test tool like Postman or curl to send a test GET request. For example, for Greeting API v1, with a username of bob set in the header, https://HOSTNAME:8065/api/greet?v=v1 returns hello from v1 bob.

    Then for Greeting API v2, with username set as a query string parameter, https:// HOSTNAME/api/greet?v=v2&username=fred returns hello from v2 fred.

Finally, if you view each front-end API version in the API Catalog, the displayed API methods also include the query string version parameter (in this case, v). And if you download the generated Swagger file, the version parameter is also included.