serverless-import-apigateway

Dynamically import an existing AWS API Gateway into your Serverless stack.

Purpose

This plugin allows you to specify the name and paths of your existing API Gateway's REST API and it will lookup and configure the provider's API Gateway with the necessary IDs.

By default, Serverless creates automatically an API Gateway for each Serverless stack or service (i.e. serverless.yml) you deploy. This is sufficient if you only have a single service and monolithic serverless.yml or can deploy your entire Serverless app at once, but if you wish to break up your monolithic Serverless app into multiple serverless.yml services and deploy each stack independently but share the same API Gateway stage/ REST API, then you want each service to use the same API Gateway.

Suppose you have the following existing Serverless service and it has an API Gateway created for an Lambda performing a status check on the root path:

service: first-service
 
provider:
  name: aws
  runtime: nodejs8.10
 
functions:
  submit:
    handler: handler.status
    events:
      - http:
          path: /
          method: GET
 
resources:
  Outputs:
    ExportedApiGatewayRestApi:
      Description: First service's API Gateway REST API resource ID
      Value:
        Ref: ApiGatewayRestApi # Logical ID 
      Export:
        Name: ExportedApiGatewayRestApi

Now if you want to create another service and add additional endpoints to this existing API Gateway, Serverless supports configuring the AWS provider to have a service use an existing API Gateway with something like the following:

service: second-service
 
provider:
  name: aws
  runtime: nodejs8.10
  apiGateway: # Optional API Gateway global config 
    restApiId: 2kd8204f8d # REST API resource ID. Default is generated by the framework 
    restApiRootResourceId: 9df5ik7fyy # Root resource ID, represent as / path 

The restApiId and restApiRootResourceId can be obtained via the AWS CLI with the aws apigateway get-rest-apis and aws apigateway get-resources commands, respectively.

However, it's not ideal to hardcode these IDs into your serverless.yml and unfortunately you cannot import the first service's exported CloudFormation stack output variable ExportedApiGatewayRestApi from within the provider's configuration using something like 'Fn::ImportValue': ExportedApiGatewayRestApi. This will produce an error.

The next best thing is to populate environment variables or pass in options from the CLI using a shell script which queries these IDs from the AWS CLI using the REST API's name so that you can reference them from the provider's configuration with ${opt:restApiId} or ${env:restApiId}. The script might look something like this:

#!/usr/bin/env bash 
 
STAGE=${1:-dev}
REGION=${2:-us-east-1}
 
RESTAPI_ID=$(aws apigateway get-rest-apis --region ${REGION} \
  --query "items[?name=='${STAGE}-first-service'].id" --output text)
ROOT_RESOURCE_ID=$(aws apigateway get-resources --region ${REGION} --rest-api-id ${RESTAPI_ID} \
  --query "items[?path=='/'].id" --output text)
 
sls deploy --restApiId ${RESTAPI_ID} --restApiRootResourceId ${ROOT_RESOURCE_ID}

This is hacky and less than ideal.

Install

npm install serverless-import-apigateway --save-dev

Configuration

Add the plugin to your serverless.yml:

plugins:
  - serverless-import-apigateway

Add the custom configuration:

custom:
  importApiGateway:
    name: ${self:provider.stage}-existing-service  # Required 
    path: /                                        # Optional 
    resources:                                     # Optional 
      - /existing
      - /existing/resource

Property	Required	Type	Default	Description
name	true	string		The name of the REST API for the AWS API Gateway to import
path	false	string	/	The root resource path to import from the REST API
resources	false	array	[]	The existing resource paths to import from the REST API

Usage

Configuration of your serverless.yml is all you need.

There are no custom commands, just run: sls deploy