[request] Versioning of APIs and Microservices

[montanaflynn]

It's quite common to version APIs to make sure that existing integrations continue to run while still making improvements, fixes and adding or removing functionality. This is done in a variety of ways including changing the URL, using custom headers, and leveraging the accept header. I believe Kong could help many API providers by allowing these conventions to map to the appropriate upstream services.

Here's a few ideas on how it could work, of course this is a hotly debated topic and Kong should aim to support all of the use-cases that already exist in the wild. Some of the ideas are currently possible, specifically the URL pattern except you have to create an API for each version, and the others would be possible if you could map requests to upstream services based on headers (which I'll make a separate issue for but it would still require creating a new API for each version) In my opinion it's best to have Kong handle versioning APIs as it's own construct tied directly to the API being versioned.

How about some examples of expected functionality following common API versioning patterns? Let's say I have an API with two versions, 1 & 2, and I'd like the "default" to be version 2:

1. Allow URLs to map to upstream services.

Request with the URL http://api.example.com/1/endpoint should send the request to example-api.v1.local
Request with the URL http://api.example.com/2/endpoint should send the request to example-api.v2.local
Request with the URL http://api.example.com/324/endpoint should probably return a 404.
Request with the URL http://api.example.com/endpoint should send the request to example-api.v2.local

2. Allow custom headers to map to upstream services.

Request with the header api-version: 1 should send the request to example-api.v1.local
Request with the header api-version: 2 should send the request to example-api.v2.local
Request with the header api-version: 55 should send the request to example-api.v2.local
Request without a api-version header should send the request to example-api.v2.local

3. Allow accept headers to map to upstream services.

Request with the header Accept: application/vnd.example.v1+json should send the request to example-api.v1.local
Request with the header Accept: application/vnd.example.v2+json should send the request to example-api.v2.local
Request with the header Accept: application/vnd.example.v55+json should send the request to example-api.v2.local
Request with out an Accept header should send the request to example-api.v2.local

There are other considerations such as deprecation timetables (I only want the v1 to work for 6 months before it returns an error with information on how to upgrade to a newer version) and dealing with authentication to only allow certain consumers access to certain versions (paying users get access to beta versions) and much more I'm possibly leaving out. I'd like to get a discussion going here to think about the best way for Kong to support versioned APIs.

Thanks for reading!

[lucamaraschi]

👍

[hims10]

+1

[mavencode01]

+1

[winston-misfit]

+1

[ayush]

This is a great suggestion and pretty well detailed. In the absence of this feature in Kong, how are others dealing with versioning?

If I have foo-service.v1.local and foo-service.v2.local running then I'd like to have:

• http://kong/foo-service/1/endpoint go to foo-service.v1.local
• http://kong/foo-service/2/endpoint go to foo-service.v2.local.

It looks like I can add two APIs to Kong like so and that would make sure all requests get routed to the appropriate service:

For foo-service.v1:

{
    "name": "foo-service.v1",
    "request_path": "/foo-service/1",
    "strip_request_path": true,
    "upstream_url": "https://foo-service.v1.local"
}

and for foo-service.v2:

{
    "name": "foo-service.v2",
    "request_path": "/foo-service/2",
    "strip_request_path": true,
    "upstream_url": "https://foo-service.v2.local"
}

But now Kong has no idea about my individual endpoints, the reals APIs of foo-service. Consequently, I can't really use plugins like ACL to secure my APIs.

It is likely that I'm missing something here. Anyone has thoughts on how to add all endpoints of foo-service into Kong while still being able to call the two versions as http://kong/foo-service/1/endpoint and http://kong/foo-service/2/endpoint?

[thibaultcha]

Anyone has thoughts on how to add all endpoints of foo-service into Kong

Before going further, I will clarify that Kong has no concept of "endpoints" on the services it proxies. Kong proxies whatever comes its way, and does not know if the requested URI matches one of your services' endpoints or not. So Kong will send any incoming request to the corresponding upstream service. Aka: Kong does not support any versioning, by doing this you simply configure two different APIs, pointing to two different locations.

Now, my understanding is also that you wish to apply an ACL plugin to both of your versions, and wish to not duplicate the plugin, but have it active on both APIs? If so, that is currently not possible, as plugins are currently tied to only 1 API at a time. This relates to #505.

Now about this issue, I do think it makes sense and I think @montanaflynn's description of the desired behavior is both precise and good enough. Having one API being able to point to multiple locations to address versioning is something to look forward to. But this is currently not implemented.

[ayush]

Thanks @thibaultcha I'll just create different APIs for each path that needs to go through ACL. I'll need to create them twice and apply ACL to them individually. Thats fine for now.

To add version prefixes to my APIs (so that I could do http://kong/foo-service/1/A and http://kong/foo-service/2/A), I could just let the request_path contain /foo-service/[version-number], strip the request path entirely and route it to the server with that [version-number] deployed using the full upstream_url.

Something like so:

For foo-service.v1:

{
    "name": "foo-service.v1.A",
    "request_path": "/foo-service/1/A",
    "strip_request_path": true,
    "upstream_url": "https://foo-service.v1.local/A"
},
{
    "name": "foo-service.v1.B",
    "request_path": "/foo-service/1/B",
    "strip_request_path": true,
    "upstream_url": "https://foo-service.v1.local/B"
}

and for foo-service.v2:

{
    "name": "foo-service.v2.A",
    "request_path": "/foo-service/2/A",
    "strip_request_path": true,
    "upstream_url": "https://foo-service.v2.local/A"
},
{
    "name": "foo-service.v2.B",
    "request_path": "/foo-service/2/B",
    "strip_request_path": true,
    "upstream_url": "https://foo-service.v2.local/B"
}

With the above:

• http://kong/foo-service/1/A will hit https://foo-service.v1.local/A
• http://kong/foo-service/2/A will hit https://foo-service.v2.local/A

And I can use ACL for my actual API A. Thanks again for your help.

[faabiosr]

Guys, I think that we can create a plugin for Header redirects will be great.

Look the ideia bellow:

Service version 1: /apis

{
    "name": "foo-service.v1",
    "request_path": "/foo-service-v1",
    "upstream_url": "http://foo-service.v1.local"
}

Service version 2: /apis

{
    "name": "foo-service.v2",
    "request_path": "/foo-service-v2",
    "upstream_url": "http://foo-service.v2.local"
}

Api: /apis

{
    "name": "foo-service",
    "request_path": "/foo-service",
    "upstream_url": "http://foo-service.local"
}

Enable Plugin: /apis/{api}/plugins

{
    "name": "header-redirect",
    "header": "api-version",
    "default": "v2",
    "config.values[1]=v1:/foo-service-v1"
    "config.values[2]=v2:/foo-service-v2"
}

[rca]

I came across this issue when searching the message:

[
    "request_path": "already exists with value '/v1'"
]

I am simply trying to have the same request_path in two APIs that have a different request_host. For example,

curl http://localhost:8001/apis/ -X POST \
  -d 'name=api1' \
  -d 'preserve_host=true' \
  -d request_host=api.example.com \
  -d 'request_path=/v1' \
  -d 'strip_request_path=true' \
-d 'upstream_url=http://172.17.0.1:8001'

Adding a second API with version v1 does not work:

curl http://localhost:8001/apis/ -X POST \
  -d 'name=api1' \
  -d 'preserve_host=true' \
  -d request_host=api.example.com \
  -d 'request_path=/v1' \
  -d 'strip_request_path=true' \
-d 'upstream_url=http://172.17.0.1:8001'

💩

Yes, I have to configure my plugins twice, but I would at least be able to have API domains with the same version.

Is there any way to have two request hosts with the same request path?

[sequences-io]

👍+1

[bmaynard]

Are there any plans for this feature request to be implemented?

[r15santro]

https://apigee.com/about/blog/developer/common-misconceptions-about-api-versioning