Amazon API Gateway

This application uses Amazon API Gateway for the backend REST API. Each REST endpoint is configured to invoke an AWS Lambda function to process each request. This page includes patterns and best practices for working with Amazon API Gateway that are used in this application.

• Define your API using OpenAPI 3
• Set API throttling limits
• Enable API logging
• Use Amazon API Gateway to generate client SDKs

Define your API using OpenAPI 3

OpenAPI is an API description format for REST APIs. It allows you to define your API endpoints, operations, and authentication methods in a single, declarative file. Defining your API using OpenAPI has several advantages:

1. OpenAPI is an open standard and includes useful tooling support, such as an editor and code generation tools for generating language-specific code to support implementing the API.
2. Amazon API Gateway natively supports creating a REST API from an OpenAPI 3 definition. Amazon API Gateway has also extended the OpenAPI format, which allows defining Amazon API Gateway specific information in the same OpenAPI definition file.

Use Amazon API Gateway OpenAPI extensions

Amazon API Gateway provides extensions to the OpenAPI specification allowing you to define API integrations, authorizers, and request validation.

Examples in this project:

1. Map an API operation to the Lambda function that should be invoked to process the operation.
2. Define constraints on API input parameters and then enable API Gateway request validation. API Gateway will automatically check API inputs based on the constraints defined in the OpenAPI definition and if validation fails, it will automatically return a 400 error back to the client without invoking your Lambda function to process the request. Caveat: You must specify an error message for the case where the request body contains the validation error, otherwise the client will receive a generic, unhelpful error message.

Use AWS::Serverless::Api in your CloudFormation template

AWS::Serverless::Api is a special resource type provided by AWS SAM, which simplifies configuration of API Gateway REST APIs when using AWS CloudFormation. When using AWS::Serverless::Api, there are additional best practices to note:

1. When authoring your own OpenAPI document, put it in a separate file and use the CloudFormation-provided AWS::Include transform to include it in the DefinitionBody property of the AWS::Serverless::Api resource. This has multiple advantages:
   1. It allows you to use CloudFormation intrinsic functions within your OpenAPI document, which is very useful for Amazon API Gateway extensions that require region and accountId information.
   2. Having your OpenAPI definition in its own file makes it easy to pass it to tools like swagger codegen to generate code from the definition.
   3. AWS SAM has some convenience features, such as adding CORS and authorizer support, where it needs access to make updates to your OpenAPI document during deployment. Normally, defining the OpenAPI document in a separate file means you can't use these SAM features. However, if you use AWS::Include, SAM will still be able to access to modify the OpenAPI definition at deployment time so these features are still available to you.
2. Explicitly set the OpenApiVersion property of AWS::Serverless::Api to the OpenAPI version you are using, even though it's already specified as part of the OpenAPI document. This is required to opt in to a SAM bugfix.

Examples in this project:

1. Using AWS::Serverless::Api to define a REST API.
2. OpenAPI document is in a separate file and then included into the template using AWS::Include. Doing this allows the use of CloudFormation intrinsic functions within the OpenAPI document.
3. Setting the OpenApiVersion property on AWS::Serverless::Api.

Set API throttling limits

Set throttling limits on your REST API to prevent callers from abusing your service. One of the primary benefits of serverless is it can seamlessly scale to any volume and you only pay for what you use. However, if someone abuses your service and calls your API at a very high volume, this can drive your costs up. Prevent this by setting throttling limits on your API.

Examples in this project:

1. Setting API throttling limits

Enable API logging

Amazon API Gateway supports two types of API logging in CloudWatch: execution logging and access logging.

Execution Logging

Execution logging provides detailed logs for each API request. It can be enabled to log either at the INFO or ERROR level. In test environments, it's good to log at the INFO level for easier debugging. For very high volume APIs, the log level can be set to ERROR in production to reduce cost. API Gateway also has a setting to enable data trace, which logs request and response data to the execution log. This can be helpful in test environments for debugging, but should NOT be enabled in production environments to protect customer data.

Access Logging

Access logging provides a single, highly structured log per request to the API. When used together with CloudWatch Insights, this becomes a powerful way to quickly understand how your API is being used.

For more information on setting up logging in Amazon API Gateway, see the Developer Guide.

Examples in this project:

1. Enabling logging first requires creating an IAM role that allows API Gateway to push logs to CloudWatch and associating it with API Gateway.
2. Enabling execution logging at the INFO level with data trace only enabled in non-prod stages.
3. Enabling access logging first requires defining a log group for the access logs, then enabling it on the API and defining the format of the log.

Use Amazon API Gateway to generate client SDKs

Amazon API Gateway provides an API that will generate a client SDK for an Amazon API Gateway API. This is useful for generating client SDKs in different languages to publish to language-specific package repositories or to generate client SDKs used for integration tests against the API.

Examples in this project:

1. The backend integration tests use an Amazon API Gateway generated Java SDK to call the REST API. A script is run manually against a deployed instance of the backend service. The script uses the AWS CLI to call Amazon API Gateway's get-sdk operation on the deployed backend. The generated SDK client code is then committed to the repository as test source code.