Api Gateway naming

Hello guys, I’m very excited and evaluating serverless to be the framework helping our next big project, very promising… I came here looking for some expertise and guidance.

Question 1 -
I noticed that when I deploy my service my APIgateways are named [stage]_[servicename]… is this the default behaviour? why can’t I have my Api Gateway API being named after my service, and then use the stages in the APi gateway to reflect stage or prod?

This is how my serverles.yml describes the service stages

  name: aws
  runtime: nodejs4.3
  stage: ${opt:stage, self:custom.defaultStage}
  profile: ${self:custom.profiles.${self:provider.stage}}

  defaultStage: dev
    dev: mp_dev
    prod: mp_prod

When I deploy it, I end with an API Gateway API named dev-aws-nodejs

If I deploy for the --stage prod, I end with another api gateway API named prod-aws-nodejs

And off course when i try to obtain the SDK for those APIs, I end with a CLASS DevAwsNodejs.class, ugly

Question 2-
Additionally, is there any guidance regarding API versioning? down the road that always becomes an important feature, but I’m not sure how you guys propose I name versions 2 and 3 of my APIs. should they be separata handlers of the same service?

What I tried is:

  1. I defined 2 functions
  2. for each function I defined a path like so:
    path: V2/user

Is there a better, suggested way you guys are doing it?

Thanks in advance for the support, I think solving this two open questions will allow me to move forward with serverless

@flomotlik I am facing same problem as it’s described above.

Regarding naming, you can use custom resources to overwrite the name, basically you edit the CF template and set a different name for it.

Regarding versioning, it is probably the best way to do it the way you proposed for now, but we’re also going to work on a different APIG/service support where you can have a service that is only there to set up APIG and then you can have other services that hook into that one APIG. So the resources are still in separate stacks and its all managed through Cloudformation, but you can have one APIG.

@flomotlik I have renamed api gateway with custom resource however only cloudformation-template-create-stack.json is updated and cloudformation-template-update-stack.json still contains stage prefix:

NOTE: I am using serverless v1.0.0


      Type: AWS::ApiGateway::RestApi
        Name: example


    "ApiGatewayRestApi": {
      "Type": "AWS::ApiGateway::RestApi",
      "Properties": {
        "Name": "example"


    "ApiGatewayRestApi": {
      "Type": "AWS::ApiGateway::RestApi",
      "Properties": {
        "Name": "dev-example"

Is this normal behaviour as I would expect whatever is defined in custom resource it should overwrite both create and update stacks?

Yup thats a bug that was introduced with V1. We’re working on fixing this as quickly as possible.

Hey guys, any news on this?

As others have mentioned, the custom resources do overwrite the name, but then just create several APIs with the same name for different stages…
I know the guideline is to use separate AWS accounts per stage, but in small teams/companies the overhead would be quite absurd.

Being a happy 0.5.x user, this is not a nice surprise… should I brace for more?

Only this week I’ve been able to setup an API Gateway with a custom name. I haven’t had it create multiple gateways unless I’ve been using multiple Serverless configurations sharing the same resources template.

I believe this is because each configuration has no idea about creating or updating shared resources. It just thinks that it manages the resources and no other configuration does.

It works when you have all of your functions/api endpoints managed by one Serverless configuration. Adding multiple Serverless configurations will produce multiple Api Gateways.

Hi David, thanks for responding. Just to be sure: have you tried with multiple stages?

Is there anything further on this? or planned feature in the future? At the moment, my lambda and api gateway admin pages are getting filled with different entries for each stage.