Step 3: Test your API
X- Ray
For a complete list of API Gateway feature releases, see Document history (p. 820).
API Gateway use cases
API Gateway use cases
Topics
• Use API Gateway to create HTTP APIs (p. 3)
• Use API Gateway to create REST APIs (p. 3)
• Use API Gateway to create WebSocket APIs (p. 4)
• Who uses API Gateway? (p. 4)
Use API Gateway to create HTTP APIs
HTTP APIs enable you to create RESTful APIs with lower latency and lower cost than REST APIs.
You can use HTTP APIs to send requests to AWS Lambda functions or to any publicly routable HTTP endpoint.
For example, you can create an HTTP API that integrates with a Lambda function on the backend. When a client calls your API, API Gateway sends the request to the Lambda function and returns the function's response to the client.
HTTP APIs support OpenID Connect and OAuth 2.0 authorization. They come with built-in support for cross-origin resource sharing (CORS) and automatic deployments.
To learn more, see the section called “Choosing HTTP API or REST API ” (p. 9).
Use API Gateway to create REST APIs
An API Gateway REST API is made up of resources and methods. A resource is a logical entity that an app can access through a resource path. A method corresponds to a REST API request that is submitted by the user of your API and the response returned to the user.
For example, /incomes could be the path of a resource representing the income of the app user. A resource can have one or more operations that are defined by appropriate HTTP verbs such as GET, POST, PUT, PATCH, and DELETE. A combination of a resource path and an operation identifies a method of the API. For example, a POST /incomes method could add an income earned by the caller, and a GET / expenses method could query the reported expenses incurred by the caller.
The app doesn't need to know where the requested data is stored and fetched from on the backend. In API Gateway REST APIs, the frontend is encapsulated by method requests and method responses. The API interfaces with the backend by means of integration requests and integration responses.
For example, with DynamoDB as the backend, the API developer sets up the integration request to forward the incoming method request to the chosen backend. The setup includes specifications of an appropriate DynamoDB action, required IAM role and policies, and required input data transformation.
The backend returns the result to API Gateway as an integration response.
To route the integration response to an appropriate method response (of a given HTTP status code) to the client, you can configure the integration response to map required response parameters from integration to method. You then translate the output data format of the backend to that of the frontend, if necessary. API Gateway enables you to define a schema or model for the payload to facilitate setting up the body mapping template.
API Gateway provides REST API management functionality such as the following:
• Support for generating SDKs and creating API documentation using API Gateway extensions to OpenAPI
Use API Gateway to create WebSocket APIs
• Throttling of HTTP requests
Use API Gateway to create WebSocket APIs
In a WebSocket API, the client and the server can both send messages to each other at any time. Backend servers can easily push data to connected users and devices, avoiding the need to implement complex polling mechanisms.
For example, you could build a serverless application using an API Gateway WebSocket API and AWS Lambda to send and receive messages to and from individual users or groups of users in a chat room. Or you could invoke backend services such as AWS Lambda, Amazon Kinesis, or an HTTP endpoint based on message content.
You can use API Gateway WebSocket APIs to build secure, real-time communication applications without having to provision or manage any servers to manage connections or large-scale data exchanges.
Targeted use cases include real-time applications such as the following:
• Chat applications
• Real-time dashboards such as stock tickers
• Real-time alerts and notifications
API Gateway provides WebSocket API management functionality such as the following:
• Monitoring and throttling of connections and messages
• Using AWS X-Ray to trace messages as they travel through the APIs to backend services
• Easy integration with HTTP/HTTPS endpoints
Who uses API Gateway?
There are two kinds of developers who use API Gateway: API developers and app developers.
An API developer creates and deploys an API to enable the required functionality in API Gateway. The API developer must be an IAM user in the AWS account that owns the API.
An app developer builds a functioning application to call AWS services by invoking a WebSocket or REST API created by an API developer in API Gateway.
The app developer is the customer of the API developer. The app developer doesn't need to have an AWS account, provided that the API either doesn't require IAM permissions or supports authorization of users through third-party federated identity providers supported by Amazon Cognito user pool identity federation. Such identity providers include Amazon, Amazon Cognito user pools, Facebook, and Google.
Creating and managing an API Gateway API
An API developer works with the API Gateway service component for API management, named apigateway, to create, configure, and deploy an API.
As an API developer, you can create and manage an API by using the API Gateway console, described in Getting started with API Gateway (p. 13), or by calling the API references (p. 808). There are several ways to call this API. They include using the AWS Command Line Interface (AWS CLI), or by using an AWS SDK. In addition, you can enable API creation with AWS CloudFormation templates or (in the case of REST APIs and HTTP APIs) Working with API Gateway extensions to OpenAPI (p. 740).
For a list of Regions where API Gateway is available, as well as the associated control service endpoints, see Amazon API Gateway Endpoints and Quotas.
Accessing API Gateway
Calling an API Gateway API
An app developer works with the API Gateway service component for API execution, named execute-api, to invoke an API that was created or deployed in API Gateway. The underlying programming entities are exposed by the created API. There are several ways to call such an API. To learn more, see Invoking a REST API in Amazon API Gateway (p. 454) and Invoking a WebSocket API (p. 720).
Accessing API Gateway
You can access Amazon API Gateway in the following ways:
• AWS Management Console – The AWS Management Console provides a web interface for creating and managing APIs. After you complete the steps in Prerequisites (p. 12), you can access the API Gateway console at https://console.aws.amazon.com/apigateway.
• AWS SDKs – If you're using a programming language that AWS provides an SDK for, you can use an SDK to access API Gateway. SDKs simplify authentication, integrate easily with your development environment, and provide access to API Gateway commands. For more information, see Tools for Amazon Web Services.
• API Gateway V1 and V2 APIs – If you're using a programming language that an SDK isn't available for, see the Amazon API Gateway Version 1 API Reference and Amazon API Gateway Version 2 API Reference.
• AWS Command Line Interface – For more information, see Getting Set Up with the AWS Command Line Interface in the AWS Command Line Interface User Guide.
• AWS Tools for Windows PowerShell – For more information, see Setting Up the AWS Tools for Windows PowerShell in the AWS Tools for Windows PowerShell User Guide.
Part of AWS serverless infrastructure
Together with AWS Lambda, API Gateway forms the app-facing part of the AWS serverless infrastructure.
For an app to call publicly available AWS services, you can use Lambda to interact with required services and expose Lambda functions through API methods in API Gateway. AWS Lambda runs your code on a highly available computing infrastructure. It performs the necessary execution and administration of computing resources. To enable serverless applications, API Gateway supports streamlined proxy integrations (p. 323) with AWS Lambda and HTTP endpoints.
How to get started with Amazon API Gateway
For an introduction to Amazon API Gateway, see the following:
• Getting started (p. 13), which provides a walkthrough for creating an HTTP API.
• Serverless land, which provides instructional videos.
Amazon API Gateway concepts
API Gateway
API Gateway is an AWS service that supports the following:
API Gateway concepts
• Creating, deploying, and managing a RESTful application programming interface (API) to expose backend HTTP endpoints, AWS Lambda functions, or other AWS services.
• Creating, deploying, and managing a WebSocket API to expose AWS Lambda functions or other AWS services.
• Invoking exposed API methods through the frontend HTTP and WebSocket endpoints.
API Gateway REST API
A collection of HTTP resources and methods that are integrated with backend HTTP endpoints, Lambda functions, or other AWS services. You can deploy this collection in one or more stages.
Typically, API resources are organized in a resource tree according to the application logic. Each API resource can expose one or more API methods that have unique HTTP verbs supported by API Gateway. For more information, see the section called “Choosing HTTP API or REST API ” (p. 9).
API Gateway HTTP API
A collection of routes and methods that are integrated with backend HTTP endpoints or Lambda functions. You can deploy this collection in one or more stages. Each route can expose one or more API methods that have unique HTTP verbs supported by API Gateway. For more information, see the section called “Choosing HTTP API or REST API ” (p. 9).
API Gateway WebSocket API
A collection of WebSocket routes and route keys that are integrated with backend HTTP endpoints, Lambda functions, or other AWS services. You can deploy this collection in one or more stages.
API methods are invoked through frontend WebSocket connections that you can associate with a registered custom domain name.
API deployment
A point-in-time snapshot of your API Gateway API. To be available for clients to use, the deployment must be associated with one or more API stages.
API developer
Your AWS account that owns an API Gateway deployment (for example, a service provider that also supports programmatic access).
API endpoint
A hostname for an API in API Gateway that is deployed to a specific Region. The hostname is of the form {api-id}.execute-api.{region}.amazonaws.com. The following types of API endpoints are supported:
• Edge-optimized API endpoint (p. 7)
• Private API endpoint (p. 8)
• Regional API endpoint (p. 8) API key
An alphanumeric string that API Gateway uses to identify an app developer who uses your REST or WebSocket API. API Gateway can generate API keys on your behalf, or you can import them from a CSV file. You can use API keys together with Lambda authorizers (p. 295) or usage plans (p. 545) to control access to your APIs.
See API endpoints (p. 6).
API owner
See API developer (p. 6).
API stage
A logical reference to a lifecycle state of your API (for example, 'dev', 'prod', 'beta', 'v2'). API stages are identified by API ID and stage name.
API Gateway concepts
App developer
An app creator who may or may not have an AWS account and interacts with the API that you, the API developer, have deployed. App developers are your customers. An app developer is typically identified by an API key (p. 6).
Callback URL
When a new client is connected to through a WebSocket connection, you can call an integration in API Gateway to store the client's callback URL. You can then use that callback URL to send messages to the client from the backend system.
Developer portal
An application that allows your customers to register, discover, and subscribe to your API products (API Gateway usage plans), manage their API keys, and view their usage metrics for your APIs.
Edge-optimized API endpoint
The default hostname of an API Gateway API that is deployed to the specified Region while using a CloudFront distribution to facilitate client access typically from across AWS Regions. API requests are routed to the nearest CloudFront Point of Presence (POP), which typically improves connection time for geographically diverse clients.
See API endpoints (p. 6).
Integration request
The internal interface of a WebSocket API route or REST API method in API Gateway, in which you map the body of a route request or the parameters and body of a method request to the formats required by the backend.
Integration response
The internal interface of a WebSocket API route or REST API method in API Gateway, in which you map the status codes, headers, and payload that are received from the backend to the response format that is returned to a client app.
Mapping template
A script in Velocity Template Language (VTL) that transforms a request body from the frontend data format to the backend data format, or that transforms a response body from the backend data format to the frontend data format. Mapping templates can be specified in the integration request or in the integration response. They can reference data made available at runtime as context and stage variables.
The mapping can be as simple as an identity transform that passes the headers or body through the integration as-is from the client to the backend for a request. The same is true for a response, in which the payload is passed from the backend to the client.
Method request
The public interface of an API method in API Gateway that defines the parameters and body that an app developer must send in requests to access the backend through the API.
Method response
The public interface of a REST API that defines the status codes, headers, and body models that an app developer should expect in responses from the API.
Mock integration
In a mock integration, API responses are generated from API Gateway directly, without the need for an integration backend. As an API developer, you decide how API Gateway responds to a mock integration request. For this, you configure the method's integration request and integration response to associate a response with a given status code.
API Gateway concepts
Model
A data schema specifying the data structure of a request or response payload. A model is required for generating a strongly typed SDK of an API. It is also used to validate payloads. A model is convenient for generating a sample mapping template to initiate creation of a production mapping template. Although useful, a model is not required for creating a mapping template.
Private API
See Private API endpoint (p. 8).
Private API endpoint
An API endpoint that is exposed through interface VPC endpoints and allows a client to securely access private API resources inside a VPC. Private APIs are isolated from the public internet, and they can only be accessed using VPC endpoints for API Gateway that have been granted access.
Private integration
An API Gateway integration type for a client to access resources inside a customer's VPC through a private REST API endpoint without exposing the resources to the public internet.
Proxy integration
A simplified API Gateway integration configuration. You can set up a proxy integration as an HTTP proxy integration or a Lambda proxy integration.
For HTTP proxy integration, API Gateway passes the entire request and response between the frontend and an HTTP backend. For Lambda proxy integration, API Gateway sends the entire request as input to a backend Lambda function. API Gateway then transforms the Lambda function output to a frontend HTTP response.
In REST APIs, proxy integration is most commonly used with a proxy resource, which is represented by a greedy path variable (for example, {proxy+}) combined with a catch-all ANY method.
Quick create
You can use quick create to simplify creating an HTTP API. Quick create creates an API with a Lambda or HTTP integration, a default catch-all route, and a default stage that is configured to automatically deploy changes. For more information, see the section called “Create an HTTP API by using the AWS CLI” (p. 183).
Regional API endpoint
The host name of an API that is deployed to the specified Region and intended to serve clients, such as EC2 instances, in the same AWS Region. API requests are targeted directly to the Region-specific API Gateway API without going through any CloudFront distribution. For in-Region requests, a Regional endpoint bypasses the unnecessary round trip to a CloudFront distribution.
In addition, you can apply latency-based routing on Regional endpoints to deploy an API to multiple Regions using the same Regional API endpoint configuration, set the same custom domain name for each deployed API, and configure latency-based DNS records in Route 53 to route client requests to the Region that has the lowest latency.
See API endpoints (p. 6).
Route
A WebSocket route in API Gateway is used to direct incoming messages to a specific integration, such as an AWS Lambda function, based on the content of the message. When you define your WebSocket API, you specify a route key and an integration backend. The route key is an attribute in the message body. When the route key is matched in an incoming message, the integration backend is invoked.
Choosing HTTP API or REST API
A default route can also be set for non-matching route keys or to specify a proxy model that passes the message through as-is to backend components that perform the routing and process the request.
Route request
The public interface of a WebSocket API method in API Gateway that defines the body that an app developer must send in the requests to access the backend through the API.
Route response
The public interface of a WebSocket API that defines the status codes, headers, and body models that an app developer should expect from API Gateway.
Usage plan
A usage plan (p. 545) provides selected API clients with access to one or more deployed REST or WebSocket APIs. You can use a usage plan to configure throttling and quota limits, which are enforced on individual client API keys.
WebSocket connection
API Gateway maintains a persistent connection between clients and API Gateway itself. There is no persistent connection between API Gateway and backend integrations such as Lambda functions.
Backend services are invoked as needed, based on the content of messages received from clients.
Choosing between HTTP APIs and REST APIs
HTTP APIs are designed for low-latency, cost-effective integrations with AWS services, including AWS Lambda, and HTTP endpoints. HTTP APIs support OIDC and OAuth 2.0 authorization, and come with built-in support for CORS and automatic deployments. Previous-generation REST APIs currently offer more features.
The following tables summarize core features that are available in HTTP APIs and REST APIs.
Authorizers HTTP API REST API
AWS Lambda ✓ ✓
IAM ✓ ✓
Amazon Cognito ✓ * ✓
Native OpenID Connect / OAuth
2.0 ✓
* You can use Amazon Cognito as a JWT issuer.
Integration HTTP API REST API
Public HTTP endpoints ✓ ✓
Lambda ✓ ✓
AWS services ✓ ✓
Private integrations with
Application Load Balancers ✓
Choosing HTTP API or REST API
Integration HTTP API REST API
Private integrations with
Network Load Balancers ✓ ✓
Private integrations with AWS
Cloud Map ✓
Mock ✓
API management HTTP API REST API
Usage plans ✓
API keys ✓
Custom domain names ✓ * ✓
* HTTP APIs don't support TLS 1.0.
Development HTTP API REST API
API caching ✓
Request parameter
transformation ✓ ✓
Request body transformation ✓
Request / response validation ✓
Test invocation ✓
CORS configuration ✓ ✓ *
Automatic deployments ✓
Default stage ✓
Default route ✓
Default route ✓