2

I keep seeing comments on how to do URI versioning in API Gateway, and these all say the same thing,

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

However, when you try to create a Custom Domain Name with a "/" in it, API Gateway responds with "Invalid Domain Name". So if you try to do it on the mapping, you get something similar mentioning the special characters you can use, and "/" is not one of them. So your only option is to use the Stage variables which these posts mention the challenges of doing it that way.

Additionally, if you just make it "v1" with no slash, then we are unable to have a custom domain like "api.whatever.com". Then makes the custom domain be specific to an API area that needs to be versioned. Ex. "stores.whatever.com". This causes each API to have their own subdomain.

URI-based Versioning for AWS API Gateway API Versioning with AWS API Gateway

Sorry for asking a new question, but I'm not allowed to add a comment on the posts.

API Gateway Custom Domain Name Mapping

Jim
  • 121
  • 1
  • 8
  • I've deleted my answer because it clearly doesn't answer your question. I think the approach to allow different areas would be to include the areas in the API definition and version the API, so you'd have v1/stores instead of stores/v1. The path would just be v1, but the API definition would include the areas. – Jason Wadsworth Aug 06 '20 at 15:23
  • Thanks for giving it a go. 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). But the only place left to do URI versioning is in the resources, and still have the Custom Domain and API mapping the way they want...since those cannot have "/" in the paths. – Jim Aug 07 '20 at 19:41

1 Answers1

0

I'm not sure I understand the request here, let me try to clarify. When a request comes in to your custom domain name api.whatever.com, API Gateway needs to determine where to send the request. API Gateway will look at the path and then determine if there are any API:STAGE mappings for that path. You can configure an empty base path mapping on a custom domain name, but then all requests without a path to that custom domain name will be routed to the API:STAGE mapping. It seems like you're trying to route requests to either api.whatever.com or stores.whatever.com, you can do this with two custom domain names each with their own empty base path mapping. For example:

Custom domain name1: api.whatever.com

  • api-id: 12345
  • stage: Live
  • api-mapping-key: NULL

Custom domain name2: stores.whatever.com

  • api-id: 67890
  • stage: Beta
  • api-mapping-key: NULL

Your clients will have to specify the proper domain name when calling your APIs.

DonBushell
  • 1
  • 1
  • 1
    The question is how to handle versioning the API. In other answers on API Versioning via URI Versioning on StackOverflow, it's said to NOT add a "v1" in your resource and to add it into your API Mapping in the Custom Domain name portion. However, if you have a generic custom domain name such as "api.whatever.com", and also have multiple apis, like "stores" and "inventory", you have no place to add the "v1" because you cannot have "/" in the API Mapping of the Custom Domain name. Therefore, all this is left is to add "v1" as the top level resource of your api. – Jim Aug 18 '20 at 21:15
  • Could you name your APIs "storesV1", "storesV2", "inventoryV1", "inventoryV2" and then configure your custom domain name base path mappings to refer to those APIs? Following the CDN:API:STAGE:PATH format, the mapping would look like: `api.whatever.com:storesV1:Live:v1`, and `api.whatever.com:storesV2:Live:v2`. This would mean customers that call `api.whatever.com/v2` would have their requests routed to the Live stage of the "storesv2" API – DonBushell Aug 18 '20 at 21:57
  • if I understand what you're saying, the v1 ends up as a resource in the API. Which is fine and what I did, but the advice from Stefano Buliani, was to not put the version as a resource in the API and build it into the API Mapping. So the way I have it is how you explained it (i think); CDN = api.whatever.com, API:STAGE = storesV1:Live -> storefinder, PATH = /v1/stores; /v1/stores/{number}...e.g. api.whatever.com/storefinder/v1/stores and api.whatever.com/storefinder/v1/stores/14. – Jim Aug 19 '20 at 21:06
  • No, don't create a /v1 resource in your API. Your API will start with a `/` root resource. Create a "stores" resource attached to the root. In your custom domain name base path mapping you will do: `api.whatever.com:storesV1:Live:stores`. This means that when clients call `api.whatever.com/stores`, API Gateway will map those requests to the `Live` stage of your `storesV1` API while keeping `v1` out of the stage and path. When you want to version your API, you can update your base path mapping. Hope this helps! – DonBushell Aug 21 '20 at 21:38
  • Unfortunately it doesn’t. We already have a situation where we need v0 (aka /stores) and v1 in place at the same time until we can update our mobile app to consume v1. It sounds like adding /v1 in the resource is the only proper way to get URI versioning until the API Gateway team allows “/“ in the base path mapping. – Jim Aug 22 '20 at 23:09