Why the stage suffix?

Hello, when deploying my service, why is -dev suffix added to the deployed function as well as to the API Gateway even though there’s a Stage that clearly identifies that this is dev? As a side-effect of this, I get the following error when trying to use my API key:

An error occurred while provisioning your stack: ApiGatewayApiKey1 - apiKeyName already exists in stack arn:aws:cloudformation:us-west-2:4565445645:stack/my-service-prod/GUID. (actual names/numbers replaced)

This is of course since my-service is being deployed with a dev and a prod suffix every time. Is this by design? If not, how can I work around it?

My understanding is that the stage variable is originally from API Gateway, and is now synonymous with “environment”.

Stage is one of my pet peeves about API Gateway - nothing else in AWS has the idea of stages like it does, so having it there feels really clunky. Unfortunately stage is not something you can avoid in API GW, so SLS had to work with it.

You can refer to the stage value through Serverless Variables
usually with something like ${opt:stage} which will get the stage value passed in the command line options.

Thank you for your response. However, I believe I’ve not explained myself correctly: I do not mind the stage “section” within API Gateway; what I do not understand is why when I run serverless deploy then serverless deploy --stage prod (for example) I get two different API Gateways in the first place, with the stage suffix added to the name?

Oh, I misunderstood you.

It sounds like a bug if those two commands produce different deployments; The resource name should include something to make it unique (or let CloudFormation name it uniquely).

The API Gateway and Serverless Framework stages are closely related but not the same thing. One of the early decisions with Serverless was that each stage should be a complete deployment with everything you need (new Lambda’s, API Gateway, Dynamo DB Tables, etc). This is the only way to cleanly deploy the same app to different environments.

That’s why you get two different API Gateways.

When creating the API Gateway it just happens to use the Serverless Framework stage name as the stage for the API Gateway.