What is a "stage" in the context of amazon api gateway?

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.

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.

I also wouldn't want to use Stages for versioning my APIs. (As versioning REST APIs is a huge anti-pattern)

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

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.