aws-api-gateway

The complete AWS API Gateway Framework, powered by Serverless Components.

Features

• Create & manage new API Gateway REST APIs with very simple configuration.
• Extend Existing API Gateway REST APIs without disrupting other services.
• Integrate with AWS Lambda via the aws-lambda component
• Authorize requests with AWS Lambda authorizers

(coming soon)

• Serverless custom endpoints
• HTTP API endpoints (websockets and apigatewayv2 endpoints)
• apikey management
• domain name management

Options

You have two sets of options, base options that apply to the whole gateway and per endpoint options. The base options appear under the inputs field of the base object below, all are optional:

restApi:
  component: "@parkhub/aws-api-gateway"
  inputs:
    name: API Name
    id: ID of existing api
    description: Description of API purpose
    minimumCompressionSize: 1048575       # Set size that gateway starts compressing return size
    binaryMediaTypes:                     # Extra media types to add to gateway
      - multipart/form-data
    deploymentDescription: description
    stage: development
    mode: update mode (merge | overwrite)
    cors: true                            # Setup Cross-Origin

The above default as:

{
name: 'Test API',
region: 'us-east-1',
description: 'Public API',
minimumCompressionSize: 1048576,
binaryMediaTypes: ['multipart/form-data'],
deploymentDescription: new Date().toISOString(),
mode: 'overwrite'
}

Per Endpoint options are set on each of the elements of the endpoint array. Currently two types of enpoints are accepted custom http and lambda proxy. You use http by specifying a URI to hit and lambda by specifying a function. Function trumps url.

restApi:
  component: "@parkhub/aws-api-gateway"
  inputs:
    description: Serverless REST API
    endpoints:
      - path: /users
        method: POST
        function: Function Name
        authorizer: Authorizer Name
      - path: /users
        method: GET
        URI: http://example.com/users

• path: gateway path
• method: gateway method
• function: lambda proxy function name (required if no URI)
• URI: uri of the service endpoint to hit
• authorizer: Gateway authorizer name
• validator: gateway input validator (0: Body, 1:BodyAndParams, 2: Params, def: NONE)
• params: input parameters to setup
  • path: path is setup from root path, param path is used for documentation only
  • querystrings: takes either {key:bool} for simple required/not, {key:obj} for documentation, and {key:string} for hardcoding a value
    • key:
      • value: Bool (required/not)
      • type: documenting type
      • def: documenting default
      • example: documenting example
      • description: documenting description
• headers: takes the same set of values as params
• keys: - value - description
• template: string velocity code for input transformation
• responses: array of objects
  • code: http return code
  • model: json schema for validating return
  • template: velocity code for output transformation

Recommendations

Use @parkhub/config https://github.com/parkhub/config to setup environment and stage variables and handle them in the configuration. With the config endpoint you can pass flags with defaults, import other yaml files and setup variables that can use eachother as variables to make env changes simple and automatic.

config:
  component: "@parkhub/config"
  inputs:
    flags:
      stage: dev
    files:
      outputModels: "./outputModels.yml"
      inputModels: "./inputModels.yml"
    environment:
      HOST: (custom.(flags.stage)-host)
    custom:
      dev-host: http://dev.example.com
      qa-host: http://qa.example.com

For reusable configurations use yaml pointers and other conviences. Declare them at the top of the file and reference them later.

headers: &headers
  Content-type: application/json
  
*headers

Example

Table of Contents

1. Install
2. Configure
3. Deploy

1. Install

$ npm install -g serverless

2. Configure

You can configure the component to either create a new REST API from scratch, or extend an existing one.

Creating REST APIs

You can create new REST APIs by specifying the endpoints you'd like to create, and optionally passing a name and description for your new REST API. You may also choose between a lambda proxy, or http integration by using the function or URI field respectively. The default api settings are:

{
  "name": "Test API",
  "region": "us-east-1",
  "description": "Public API",
  "minimumCompressionSize": 1048576,
  "binaryMediaTypes": ["multipart/form-data"],
  "deploymentDescription": "new Date().toISOString()",
  "mode": "overwrite"
}

The following is an example with all available options:

restApi:
  component: "@parkhub/aws-api-gateway"
  inputs:
    name: Developer API
    description: Rest API
    minimumCompressionSize: 1048576
    binaryMediaTypes:
      - multipart/form-data
    deploymentDescription: "Deploying api"
    stage: dev
    cors: true
    mode: merge
    endpoints:
      - path: /events
        mehtod: GET
        function: getEvents-${stage} # refer to functions with name only
        authorizer: authorize-events # custom lambda authorizer supported
        validator: 2 # validation type to use 0: Body only, 1: Body and Params, 2: Params only

      - path: /events
        method: POST
        function: ${createUser.name}
        authorizer: ${auth.name}
      - path: /users
        method: GET
        function: ${getUsers.arn}
        authorizer: ${auth.name}
      - path: /users
        method: PUT
        proxyURI: https://example.com/users
        authorizer: ${auth.arn}

Extending REST APIs

You can extend existing REST APIs by specifying the REST API ID. This will only create, remove & manage the specified endpoints without removing or disrupting other endpoints.

# serverless.yml

createUser:
  component: "@serverless/aws-lambda"
  inputs:
    code: ./code
    handler: index.createUser
getUsers:
  component: "@serverless/aws-lambda"
  inputs:
    code: ./code
    handler: index.getUsers

restApi:
  component: "@serverless/aws-api-gateway"
  inputs:
    id: qwertyuiop # specify the REST API ID you'd like to extend
    endpoints:
      - path: /users
        method: POST
        function: ${createUser.name}
      - path: /users
        method: GET
        function: ${getUsers.name}

3. Deploy

$ serverless

New to Components?

Checkout the Serverless Components repo for more information.