Amazon API Gateway
Developer Guide

Creating an API in Amazon API Gateway

In Amazon API Gateway, you build an API with a collection of programmable entities known as API Gateway resources. For example, you use a RestApi resource to represent an API that can contain a collection of Resource entities. Each Resource entity can in turn have one or more Method resources. Expressed in the request parameters and body, a Method defines the application programming interface for the client to access the exposed Resource and represents an incoming request submitted by the client. You then create an Integration resource to integrate the Method with a backend endpoint, also known as the integration endpoint, by forwarding the incoming request to a specified integration endpoint URI. If necessary, you transform request parameters or body to meet the backend requirements. For responses, you can create a MethodResponse resource to represent a request response received by the client and you create an IntegrationResponse resource to represent the request response that is returned by the backend. You can configure the integration response to transform the backend response data before returning the data to the client or to pass the backend response as-is to the client.

To help your customers understand your API, you can also provide documentation for the API, as part of the API creation or after the API is created. To enable this, add a DocumentationPart resource for a supported API entity.

To control how clients call an API, use IAM permissions, a Lambda authorizer, or an Amazon Cognito user pool. To meter the use of your API, set up usage plans to throttle API requests. You can enable these when creating or updating the API.

You can perform these and other tasks by using the API Gateway console, the API Gateway REST API, the AWS CLI, or one of the AWS SDKs. We discuss how to perform these tasks next.

Choose an Endpoint Type to Set up an API Gateway API

An API endpoint refers to a host name of the API. the API endpoint can be edge-optimized or regional, depending on where the majority of your API traffic originates from. You choose a specific endpoint type when creating an API.

An edge-optimized API endpoint optimizes access to an API by geographically distributed clients through an Amazon CloudFront distribution. API requests are routed to the nearest CloudFront Point of Presence (POP) . By default, an API is created with the edge-optimized endpoint.

A regional API is intended for clients in the same region. When a client running on an EC2 instance calls an API in the same region, or when an API is intended to serve a small number of clients with high demands, a regional API reduces connection overhead.

For an edge-optimized API, you create a custom domain name that applies across all the regions. For a regional API, you create a custom domain name that is specific to the API hosting region. It is possible that a regional API deployed in different regions can have the same custom domain name.