What is a "stage" in the context of Amazon API Gateway?

Question

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?

Windtight

Answer 1

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.

Teran

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. – Calceiform

Answer 2

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.

Creatural

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. – Naiad

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 – Ld

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. – Vedi

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 – Brauer

Yeah, I'd like to hear why you consider versioning REST APIs to be an anti-pattern. – Tamayo

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 – Tricornered

Versioning REST apis is not an anti pattern. It unclear what the original poster meant. I've deleted that sentence to avoid confusion. – Hindenburg

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 – Cleat

Answer 3

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.

Moonscape

Answer 4

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.

Reindeer

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. – Licence

Answer 5

for info about no stage; deploy;

some statements are just my guesses -- I cant find good resources

---

what no stage option does

• it seems that, if you choose no stage, it just wont get deployed
  -- the option is just for choosing a stage at a later time ...

Selecting (No stage) will create a deployment of your API that is not associated with any stage.
To use this deployment, associate the deployment with a stage.

-- Aws console warning

[]
To create a deployment that is not associated with a stage, select No stage. Later, you can associate this deployment with a stage.
<>
https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-deploy-api-with-console.html

[]

Simply creating and developing an API Gateway API doesn't automatically make it callable by your users. To make it callable, you must deploy your API to a stage. \

So YES, a stage is required for the API Gateway to be usable by Postman.
<>
Does AWS API Gateway require a stage to be accessed by Postman? \

Remove Stage Name From URI

• see AWS API Gateway - Remove Stage Name From URI

meaning of deploy & stage in Api Gateway

• • To understand what truly “Deployment” in API Gateway is,

    see https://medium.com/@lancers/deployment-in-amazon-api-gateway-128c522c762e explains it well.

  • basically, you must deploy the Api so you can use it.

  API Gateway - How Deploy API works?

Kaput