URI-based Versioning for AWS API Gateway

Question

I am struggling to understand how AWS API Gateway wants me to organise my APIs such that versioning is straightforward. For example, let's say I have a simple API for getting words from a dictionary, optionally filtering the results by a query parameter. I'd like to have v1 of this be available at:

https://<my-domain>/v1/names?starts-with=<value>

However, the closest I can get API Gateway is at

https://<my-domain>/names/v1?starts-with=<value>

... which is quite backwards.

What I've got in the console is "Names API" with a "v1" resource supporting a GET method. I also have my custom domain setup to map a base path of "names" to "Names API" and stage "test". The Base path must be unique so putting "v1" there is only a short-term win; once I create my second API (e.g. Numbers API) it'll have a v1, too, and I won't be able to create a second mapping.

Any and all help is greatly appreciated as I'm out of ideas now.

Answer 1

Do not create the version path (/v1) as a resource in your API. Instead, simply call you API "Names V1" and start creating the resources (/names). When you want to make a breaking change and create a new version of the API, we recommend you create an entirely new API called "Names V2". Once again, simply create your resources without the version path.

To bring the two APIs together, you can use custom domain names. A custom domain name in API Gateway includes both a fully qualified domain name and a base path. Create two custom domain names:

• myapi.com/v1 -> points to the prod stage of the Names V1 API
• myapi.com/v2 -> points to the prod stage of the Names V2 API

This way you can keep bug-fixing v1 while making changes to v2 and deploy the two APIs independently. The custom domain name will bring them together and make them appear under the same domain (myapi.com/v2/names).

Hope this helps.