50

What is a "stage" in the context of Amazon API Gateway? What is it's purpose and how to create one?

Is there any relation to "staging" in the production/staging/development convention?

BinaryButterfly
  • 18,137
  • 13
  • 50
  • 91
american-ninja-warrior
  • 7,397
  • 11
  • 46
  • 80

4 Answers4

42

Although you can use Stages as part of a different stages in your pipeline or environments this goes against AWS best practice for managing environments.

If you want a development environment, then create a development user/account and deploy using that. Likewise other environments like Production or Pre-Production.

Which does then beg the question about what Stages actually are in AWS gateways used for? Whenever I've used them I've put a sensible placeholder there.

pzrq
  • 1,626
  • 1
  • 18
  • 24
tommyk
  • 475
  • 4
  • 7
  • 7
    I agree with this comment. API Gateway stages are mostly redundant and it's hard to imagine why I would use different stages when I can just whip up a new stack (or module in Terraform) and get much of the same functionality. – dimiguel Jun 26 '20 at 09:54
  • 1
    I also agree with this comment, not isolating between pipeline environments seems incredibly risky by opening the possibility of data leakage and all sorts of problems – Paul Carroll Mar 24 '21 at 00:24
  • 16
    Can you provide more details (perhaps a link) of the versioning anti-pattern? A quick search on Google didn't reveal anything to back up your statement. – Jonathan Holvey Aug 22 '21 at 00:52
  • 3
    Versioning REST APIs is a huge BEST PRACTICE, for instance because to be backward compatible! If thats your observation or opinion, please at least try to explain why, otherwise this could have unwanted impact on inexperienced readers – Thomas Fritz Aug 26 '22 at 09:58
  • 1
    Yeah, I'd like to hear why you consider versioning REST APIs to be an anti-pattern. – Aurelia Peters Oct 17 '22 at 22:37
  • I'm also left wondering why versioning API's is an anti-pattern? I know it was a pain in SOAP services, but even there it was sometimes worth the effort. As it turns out, at the moment I have no need to version my service however, but I do have multiple client applications which may have slightly different calling conventions. I was considering using it for that. That's not *quite* a question, but less than a statement :D – Amandalishus Nov 18 '22 at 23:04
  • 1
    Versioning REST apis is not an anti pattern. It unclear what the original poster meant. I've deleted that sentence to avoid confusion. – SCdF Dec 29 '22 at 14:31
  • I just started aws _serverless_ and following best practices, I have one account for each environments (dev, staging, prod), so I was wondering why would I need _api gateway stage_.... I guess I don't, but it's required... I wish there was some _best practices_ for cloudformation+accounts_for_env+apis+deployment – JobaDiniz Jan 26 '23 at 23:59
30

I would consider API Gateway stages as different stages in your pipeline or different environments of your stack for the same application. You can have as many stages as you want. In a simple stack, we can think of 3 stages: dev, qa and prod. Few things which you can do with stages:

  1. You will have different URL's for each stage. like https://api-gateway-domain/dev/... , https://api-gateway-domain/qa/..,https://api-gateway-domain/prod/... Basically the URL would be https://api-gateway-domain/<stage_name>/...
  2. You can go with custom domain names to associate with each stage.
  3. You can associate different usage plans for each stage.
  4. You will mostly have at least 1 stage variable to define your stage uniquely. This could be an Elastic Beanstalk URL which is different for each environment. Through stage variables, you will be calling different backend URL's for each stage.
  5. You can deploy different versions of API Gateway configurations for that application to different stages.
Robert
  • 33,429
  • 8
  • 90
  • 94
Avichal Badaya
  • 3,423
  • 1
  • 21
  • 23
  • 1
    This may be useful for beta/test in the same AWS account; you can have a beta stage (api.beta.example.com), and then a test stage (api.test.example.com). Then I could save on the number of GWs I have deployed 1 vs 2 in the account and region. – b01 Feb 11 '21 at 22:55
1

You can consider an API Gateway stage as a specific lifecycle stage or version of your API.

For example:

  • production-stage
  • development-stage
  • beta-stage

From these stages you can configure things like throttling and caching.

Dexter
  • 4,036
  • 3
  • 47
  • 55
Peter Girnus
  • 2,673
  • 1
  • 19
  • 24
  • 5
    I suppose this is correct if you have one account for your SDLC. But best practices say to have a DEV account, STAGE account and PROD. So in this use case, a stage is somewhat unnecessary. – Jack Marchetti Apr 04 '21 at 21:28
1

Use "v1". If you need to deploy breaking changes while still servicing clients that use the current version and cannot be updated, you can create v2 and keep them both running at the same time.

hernvnc
  • 827
  • 11
  • 18