@serverless/api

API

The provider agnostic 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 serverless functions via the function component
• Authorize requests with authorizer functions
• Create proxy endpoints for any URL with 3 lines of code (coming soon)
• Create mock endpoints by specifying the object you'd like to return (coming soon)
• Create & manage logs to debug API Gateway requests (coming soon)
• Protect your API with API Keys (coming soon)
• Configure throttling & rate limits (coming soon)

Table of Contents

1. Install
2. Create
3. Configure
4. Deploy

1. Install

$ npm install -g @serverless/components

2. Create

Just create the following simple boilerplate:

$ touch serverless.yml # more info in the "Configure" section below
$ touch index.js       # your lambda code
$ touch .env           # your development AWS api keys
$ touch .env.prod      # your production AWS api keys

the index.js file should look something like this:

module.exports.createUser = async (e) => {
  return {
    statusCode: 200,
    body: 'Created User'
  }
}

module.exports.getUsers = async (e) => {
  return {
    statusCode: 200,
    body: 'Got Users'
  }
}

module.exports.auth = async (event, context) => {
  return {
    principalId: 'user',
    policyDocument: {
      Version: '2012-10-17',
      Statement: [
        {
          Action: 'execute-api:Invoke',
          Effect: 'Allow',
          Resource: event.methodArn
        }
      ]
    }
  }
}

the .env files are not required if you have the aws keys set globally and you want to use a single stage, but they should look like this.

AWS_ACCESS_KEY_ID=XXX
AWS_SECRET_ACCESS_KEY=XXX

Keep reading for info on how to set up the serverless.yml file.

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

# serverless.yml

name: rest-api

createUser:
  component: "@serverless/function"
  inputs:
    name: ${name}-create-user
    code: ./code
    handler: index.createUser
getUsers:
  component: "@serverless/function"
  inputs:
    name: ${name}-get-users
    code: ./code
    handler: index.getUsers
auth:
  component: "@serverless/function"
  inputs:
    name: ${name}-auth
    code: ./code
    handler: index.auth

restApi:
  component: "@serverless/api"
  inputs:
    name: ${name}
    description: Serverless REST API
    endpoints:
      - path: /users
        method: POST
        function: ${comp:createUser}
        authorizer: ${comp:auth}
      - path: /users
        method: GET
        function: ${comp:getUsers}
        authorizer: ${comp:auth}

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

name: rest-api

createUser:
  component: "@serverless/function"
  inputs:
    name: ${name}-create-user
    code: ./code
    handler: index.createUser
getUsers:
  component: "@serverless/function"
  inputs:
    name: ${name}-get-users
    code: ./code
    handler: index.getUsers

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

4. Deploy

api (master)$ components

  myApig › outputs:
  id:  'e4asreichk'
  endpoints:  [ { path: '/users',
    method: 'POST',
    function:
     'arn:aws:lambda:us-east-1:552750238291:function:rest-api-create-user',
    url:
     'https://e4asreichk.execute-api.us-east-1.amazonaws.com/dev/users',
    id: 'jkgqlqjnf2' },
  { path: '/users',
    method: 'GET',
    function:
     'arn:aws:lambda:us-east-1:552750238291:function:rest-api-get-users',
    url:
     'https://e4asreichk.execute-api.us-east-1.amazonaws.com/dev/users',
    id: 'h7zh3r' } ]


  38s › dev › rest-api › done

api (master)$

 

New to Components?

Checkout the Serverless Components repo for more information.