19

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.

Mark
  • 1,884
  • 2
  • 25
  • 36

1 Answers1

27

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.

Stefano Buliani
  • 974
  • 7
  • 8
  • 1
    Thanks, Stefano. However, how do I map v1 of a Numbers API if the base path must be unique? That is, I don't think I can have myapi.com/v1/names and myapi.com/v1/numbers or am I misunderstanding something? – Mark Feb 07 '17 at 22:05
  • 3
    At the moment you can only have one path part in the custom domain name, so you'd have to have both the names and numbers resources in the same API. We have heard from other customers that they'd like to include multiple path parts in the domain name and it's definitely something we are considering - thanks for the feedback! – Stefano Buliani Feb 08 '17 at 16:47
  • Nice. I'll use some backup ideas for now. BTW, if you work for Amazon, you should see if stack overflow can mark you as a verified expert or something. You know like celebrities do on Twitter? It would make your answers more authoritative. – Mark Feb 08 '17 at 20:32
  • 2
    Second the need for more flexible base paths. June 2018 now and still not possible. :( – Eric Tarasoff Jun 01 '18 at 20:52
  • @StefanoBuliani lets say I have `myapi.com/v1`, `myapi.com/v2` and `myapi.com/v3`. Lets say v1 is my deprecated version, v2 is the stable version of my API and v3 is beta. I do not want version numbers in the public stable version --per REST API Guidelines. So myapi.com/v2/names and myapi.com/names should point to the same endpoint (or lets say Lambda). Is there a way to do this via base path mapping, any other ways -- within API Gateway ? – exifguy Jun 10 '18 at 23:50
  • Unfortunately not at the moment @exifguy. I'll take this feedback to the API Gateway team. – Stefano Buliani Jun 15 '18 at 19:01
  • 3
    Hello! Since it’s been more than a year since you answered, are the recommendations still valid in 2018? Thanks! – Victor Oct 30 '18 at 08:33
  • @Victor, yup, still valid. – Stefano Buliani Oct 31 '18 at 18:42
  • 1
    Frustratingly this still appears to be the case. The apigw doesn't really appear capable of supplying versioning in Uri, throttling, auth and routing in a single implementation unless you merge all your api's into a single api, which then doesn't allow lambdas to supply their own api as they would want to register under a base path. – metalisticpain Apr 08 '19 at 08:32
  • 2
    @StefanoBuliani Why is this the preferred methodology rather than using the [API Gateway Stages](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-basic-concept.html#apigateway-definition-api-stage) feature that's built into the service? – Alex Mar 11 '20 at 20:26
  • 1
    @Alex If you are planning to make breaking changes to the API - and I assume you are since you want to introduce a new major version - it's easier to keep both versions of the API alive at the same time. If needed, you can keep bug-fixing and deploying v1 independently from v2. Stages are sub-constructs of an API, working on two "very different" versions of the same API definition would quickly become difficult to manage through a single source. – Stefano Buliani Mar 12 '20 at 21:11
  • @StefanoBuliani Do you have any documenation on `AWS::Serverless::Function` with serveless template `AWS::Serverless-2016-10-31` to support create version, alias. As I am trying to point api gateway stages to lambda aliases. – Rafee Jun 08 '20 at 06:48
  • You could use the [`AutoPublishAlias` property of the function](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html#sam-function-autopublishalias). Then, in your OpenAPI definition, you can point the integration directly to the alias by adding the qualifier at the end of the ARN:` :` – Stefano Buliani Jun 09 '20 at 18:16
  • I asked this question because I didn't have enough rep to ask it here until today (stackoverflow.com/questions/63285580/api-gateway-uri-versioning). but I'm having this conversation with our Ops team, they want to have something like "api.whatever.com" then have API mappings to specific api gateways like "stores" but don't want the v1 in the resource or stages, (i don't want it in the stages). Since Custom Domain and API Mappings cannot have "/" in the paths, the only place left is in the resource. Thoughts @StefanoBuliani? Thanks in advance. – Jim Aug 10 '20 at 20:43
  • As far as I understood the answer suggested using the dedicated API GW per each API version. @StefanoBuliani is this still the only reasonable option to have API versioning in 2021? Thanks, Aleks – senleft Mar 24 '21 at 02:26
  • @StefanoBuliani the approach you are recommending is it mentioned somewhere in the official AWS API Gateway documentation. May I ask you to share a link to a documentation page or a guide from AWS on this? – interested-dev Sep 03 '21 at 16:19