1. Home
  2. Tyk Open Source API Gateway v2.x
  3. API Management
  4. API Versioning

API Versioning

Versioning an API with Tyk is very easy and should integrate easily with how your underlying API is set up.

Step 1

To activate versioning in an API, simply create a version entry in the version_data.versions section of the API Definition:

{
    "version-1": {
        "name": "version-1",
        "expires": "",            
        "use_extended_paths": true,
        "extended_paths": {
            "ignored": [
                {
                    "path": "/v1/ignored/noregex",
                    "method_actions": {
                        "GET": {
                            "action": "no_action",
                            "code": 200,
                            "data": "",
                            "headers": {
                                "x-tyk-override-test": "tyk-override",
                                "x-tyk-override-test-2": "tyk-override-2"
                            }
                        }
                    }
                }
            ],
            "white_list": [
                {
                    "path": "v1/allowed/whitelist/literal",
                    "method_actions": {
                        "GET": {
                            "action": "no_action",
                            "code": 200,
                            "data": "",
                            "headers": {
                                "x-tyk-override-test": "tyk-override",
                                "x-tyk-override-test-2": "tyk-override-2"
                            }
                        }
                    }
                },
                {
                    "path": "v1/allowed/whitelist/reply/{id}",
                    "method_actions": {
                        "GET": {
                            "action": "reply",
                            "code": 200,
                            "data": "flump",
                            "headers": {
                                "x-tyk-override-test": "tyk-override",
                                "x-tyk-override-test-2": "tyk-override-2"
                            }
                        }
                    }
                },
                {
                    "path": "v1/allowed/whitelist/{id}",
                    "method_actions": {
                        "GET": {
                            "action": "no_action",
                            "code": 200,
                            "data": "",
                            "headers": {
                                "x-tyk-override-test": "tyk-override",
                                "x-tyk-override-test-2": "tyk-override-2"
                            }
                        }
                    }
                }
            ],
            "black_list": [
                {
                    "path": "v1/disallowed/blacklist/literal",
                    "method_actions": {
                        "GET": {
                            "action": "no_action",
                            "code": 200,
                            "data": "",
                            "headers": {
                                "x-tyk-override-test": "tyk-override",
                                "x-tyk-override-test-2": "tyk-override-2"
                            }
                        }
                    }
                }
            ]
        }
    }
}

Step 2

And ensure that the definition section of the API Definition file/object is set up to find the version data:

"definition": {
    "location": "header",
    "key": "x-api-version"
}

In this section you can either set the location to header or url-param, this will tell Tyk where to try and find version information for the request. When url-param is set, Tyk will check query parameters or url-form-encoded parameters for the version key (so GET, POST, PUT, and DELETE methods can be used with data encoded in the query string or in the body of the request).

When the key is extracted from the request, the current token session is checked to see whether the user has access to the version, this is checked by attempting to match the version name against the key value. this is case sensitive.

Step 3

Finally, ensure that the API is actually set to allow versioning, this is done by setting the version_data.not_versioned value to false.

A few notes on versioning and allowing access:

  • Version expiry is applied to all keys
  • Version ignored / white-listing / black listing is applied to all keys
  • Version access control is only applied to keys which have access-control parameters applied to them. If a key has no access_rights data in the session key, then the request will be allowed through to the underlying API.

Step 4 (optional)

In many cases a versioned API will have different upstream back-end servers, in order to make it possible to target those servers when a new version flag is detected, you can use the override_target option in the version definition to set it to the host you would like to target for the specified version.

Please see the in-depth section of this guide to read about what all of the keys in the API Definition files do.