Configure REST API routing based on version query string
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 namedgreet
withusername
as header parameter, which returns ahello from v1 <username>
string. For example:GET http:///HOSTNAME:18080/api/v1/greet
-
Greeting API v2: This also includes a single
GET
method namedgreet
withusername
as a query string parameter (instead of the header parameter in Greeting API v1), and which returns ahello 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:
-
Ensure that you are logged into API Manager as an API administrator, and that the organization is enabled for API development.
-
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.
-
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
orversion
). For example: -
When query string-based version routing has been enabled, the Query string version routing setting is displayed when you select API > Frontend API, and view the Inbound tab for a selected API.
-
For each front-end API:
- Remove the version from the Resource path if necessary. For example, for Greeting API v1, you would change the default path from
api/v1
toapi
, and for Greeting API v2, change the path fromapi/v2
toapi
. - Enter the API version in the Query string version routing field instead (for example,
v1
orv2
as appropriate). You can enter any value based your chosen versioning system (for example, major or minor version, with or without the prefixv
). - Click Save. The example following shows the front-end Greeting API v1:
- Remove the version from the Resource path if necessary. For example, for Greeting API v1, you would change the default path from
-
You can use a client test tool like Postman or curl to send a test
GET
request. For example, for Greeting API v1, with ausername
ofbob
set in the header,https://HOSTNAME:8065/api/greet?v=v1
returnshello from v1 bob
.Then for Greeting API v2, with
username
set as a query string parameter,https:// HOSTNAME/api/greet?v=v2&username=fred
returnshello 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.