serverless-disable-apigateway-deployment

Disable automatic API Gateway REST deployments when using Serverless Framework.

🚨 Problem

Serverless Framework automatically creates and deploys an AWS::ApiGateway::Deployment whenever http events are defined.

This behavior:

• Forces immediate API stage updates
• Breaks centralized API deployment strategies
• Makes shared API Gateways difficult in microservice architectures

There is no built-in way to disable this behavior.

✅ Solution

This plugin removes the generated AWS::ApiGateway::Deployment resource before CloudFormation is deployed.

Result:

• API Gateway resources & methods are created
• Stage is NOT updated
• API changes go live only when YOU deploy them

📦 Installation

npm install --save-dev serverless-disable-apigateway-deployment

⚙️ Usage

Add the plugin to any Serverless service where you want to disable automatic API Gateway REST deployments.

plugins:
  - serverless-disable-apigateway-deployment

Deploy as usual:

serverless deploy

During deployment you will see logs like:

[serverless-disable-apigateway-deployment] Removed ApiGatewayDeployment123ABC

This confirms that the API Gateway deployment was successfully removed.

⚙️ Configuration

You can configure the plugin in your serverless.yml under the custom section.

custom:
  disableApiGatewayDeployment:
    logRemoved: true  # optional, default is true

Example:

service: example-service

provider:
  name: aws
  runtime: nodejs18.x

plugins:
  - serverless-disable-apigateway-deployment

custom:
  disableApiGatewayDeployment:
    logRemoved: true

functions:
  hello:
    handler: handler.hello

Options

| Option | Type | Default | Description | |------------|--------|---------|------------------------------------------------------------| | logRemoved | boolean | true | Enable or disable logging of removed API Gateway Deployment resources |

🏗️ Recommended Architecture (End-to-End)
This plugin is designed for shared API Gateway / microservice architectures.

1️⃣ api-core
Creates the shared API Gateway.

resources:
  Resources:
    SharedApi:
      Type: AWS::ApiGateway::RestApi
      Properties:
        Name: shared-api

Deploy once to create the API Gateway.

2️⃣ Microservices (service-order, service-user, etc.)
Each microservice:

• Defines HTTP routes
• Uses the shared API Gateway
• Does not deploy the API stage

plugins:
  - serverless-disable-apigateway-deployment

provider:
  apiGateway:
    restApiId: ${cf:api-core-SharedApiId}
    restApiRootResourceId: ${cf:api-core-RootResourceId}

functions:
  getOrders:
    handler: handler.getOrders
    events:
      - http:
          path: orders
          method: get

You can deploy microservices freely — the API Gateway stage will NOT be updated.

3️⃣ api-deployer (ONLY place deployments happen)
This service is responsible for making API changes live.

resources:
  Resources:
    ApiGatewayDeployment:
      Type: AWS::ApiGateway::Deployment
      Properties:
        RestApiId: ${cf:api-core-SharedApiId}
        StageName: prod

Run this service only when you want API changes to go live.

⚠️ Important Notes

• Your API Gateway must already have at least one deployment.
• Do NOT use this plugin in your API deployer service.
• Works with REST APIs only (not HTTP API v2).

Additional Note:

This plugin also prevents the "No Integration Method Found" error" in API Gateway, which can occur when:

• Deploying multiple microservices in parallel for the first time in an AWS account
• Using a shared API Gateway across services

Without this plugin, Serverless automatically creates AWS::ApiGateway::Deployment resources for each service, which can cause:

• API stage conflicts
• Missing integration methods

By removing automatic deployments:

• API Gateway resources and methods are created safely
• Stage updates only happen when you deploy the dedicated API deployer service
• You can deploy multiple services in parallel without breaking your API Gateway configuration

🧪 Compatibility

• Serverless Framework v2 & v3
• AWS API Gateway REST
• Node.js 14+