Overview

The API Gateway receives a client request, it possibly validates or transformes it, dispatches it to a backend integration, gets a response, possibly transforms it, and sends the response to the client.

Version 1

This is for a REST API.

Resources

A Resource is a part of the url path between two slashes. it can also be path variable. Resources can be nested.

Methods

HTTP-Methods like GET, POST, PUT, PATCH and DELETE. Together with the resource’s path these form an Endpoint that leads to an Integration.

Integrations

  • AWS
  • AWS_PROXY
  • HTTP
  • HTTP_PROXY
  • MOCK

For Proxy Integrations there is no Integration Request and no Integration Response configured. The request is passed directly to the endpoint.

For the other Integration Request and Response must be configured and also data mapping from the Request to the Integration Request and from the Integration Response to the Method Response.

AWS_Proxy is also known as Lambda Proxy Integration

Models

A Model is defined using json schema. It is used for client-sdk generation and also for request validation

Authorization

API Keys and custom Lambda Authorizers

Version 2

  • HTTP API
  • WebSocket API

Lower Latency and lower price.

Version 1 was verbose with many resources to configure. In version 2 A single Route can be defined for catch-all and let the backend handle the routing itself.

API Gateway V2 has more support for HTTP APIs returning CORS headers

Routes

A Route is a URL Path plus a HTTP Method.

A route can have a path variable, and this can be made greedy with a plus sign

Integration

Currently only HTTP_PROXY and AWS_PROXY (for Lambda only ?) are available for HTTP APIs.

The Integration can be reached via INTERNET or VPC_LINK

For Lambda Proxy there is a new Payload Format. You can specify payloadFormatVersion to 1.0 and 2.0.

In the Lambda Implementation you must use events.APIGatewayV2HTTPRequest or better use apex/gateway/v2

{
  "version": "2.0",
  "routeKey": "$default",
  "rawPath": "/my/path",
  "rawQueryString": "parameter1=value1&parameter1=value2&parameter2=value",
  "cookies": [
    "cookie1",
    "cookie2"
  ],
  "headers": {
    "Header1": "value1",
    "Header2": "value1,value2"
  },
  "queryStringParameters": {
    "parameter1": "value1,value2",
    "parameter2": "value"
  },
  "requestContext": {
    "accountId": "123456789012",
    "apiId": "api-id",
    "authorizer": {
      "jwt": {
        "claims": {
          "claim1": "value1",
          "claim2": "value2"
        },
        "scopes": [
          "scope1",
          "scope2"
        ]
      }
    },
    "domainName": "id.execute-api.us-east-1.amazonaws.com",
    "domainPrefix": "id",
    "http": {
      "method": "POST",
      "path": "/my/path",
      "protocol": "HTTP/1.1",
      "sourceIp": "IP",
      "userAgent": "agent"
    },
    "requestId": "id",
    "routeKey": "$default",
    "stage": "$default",
    "time": "12/Mar/2020:19:03:58 +0000",
    "timeEpoch": 1583348638390
  },
  "body": "Hello from Lambda",
  "pathParameters": {
    "parameter1": "value1"
  },
  "isBase64Encoded": false,
  "stageVariables": {
    "stageVariable1": "value1",
    "stageVariable2": "value2"
  }
}

Authorization

A JWT Authorizer can be configured

Stages

A stage is routed to via the first part of the path: https://api.example.com/PRD_STAGE/endpoint

A stage with the name $default omits this part of the path: https://api.example.com/endpoint

Deployment

A deployment is a snapshot of your API configuration. You must deploy an API for changes to take effect. If you enable automatic deployments, changes to an API are automatically released for you.

Quick Create

This feature automatically creates an API with a default route and default stage. Probably also autodeploy

In cloudformation AWS::ApiGatewayV2::Api use for quick create:

  • CredentialsArn For Lambda Integration
  • RouteKey If you don’t specify a routeKey, a default route of $default is created for catch-all
  • Target For HTTP integrations, specify a fully qualified URL. For Lambda integrations, specify a function ARN