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

``bash
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.

`yaml
plugins:
- serverless-disable-apigateway-deployment
`
Deploy as usual:
`bash
serverless deploy
`
During deployment you will see logs like:
`txt
[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.
`yaml
custom:
disableApiGatewayDeployment:
logRemoved: true # optional, default is true
`
Example:
`yaml
service: example-service

provider:
name: aws
runtime: nodejs18.x

plugins:
- serverless-disable-apigateway-deployment

custom:
disableApiGatewayDeployment:
logRemoved: true

functions:
hello:
handler: handler.hello

`

$3

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

`yaml
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

`yaml
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.

`yaml
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+