Amazon API Gateway - Developer Guide

381 Pages·2017·2.32 MB·English

by  Amazon Web Services

Amazon API Gateway
Developer Guide
Amazon API Gateway Developer Guide
Amazon API Gateway: Developer Guide
Copyright © 2022 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not
Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or
discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may
or may not be affiliated with, connected to, or sponsored by Amazon.
Amazon API Gateway Developer Guide
Table of Contents
What is Amazon API Gateway? ............................................................................................................ 1
Architecture of API Gateway........................................................................................................ 1
Features of API Gateway ............................................................................................................. 2
API Gateway use cases ................................................................................................................ 3
Use API Gateway to create REST APIs ................................................................................... 3
Use API Gateway to create HTTP APIs .................................................................................. 3
Use API Gateway to create WebSocket APIs ........................................................................... 4
Who uses API Gateway? ...................................................................................................... 4
Accessing API Gateway ............................................................................................................... 5
Part of AWS serverless infrastructure ............................................................................................ 5
How to get started with Amazon API Gateway ............................................................................... 5
API Gateway concepts................................................................................................................. 5
Choosing between REST APIs and HTTP APIs ................................................................................. 9
........................................................................................................................................ 9
Endpoint type.................................................................................................................... 9
Security........................................................................................................................... 10
Authorization................................................................................................................... 10
API management.............................................................................................................. 10
Development................................................................................................................... 11
Monitoring....................................................................................................................... 11
Integrations..................................................................................................................... 12
Prerequisites.................................................................................................................................... 13
Sign up for an AWS account ...................................................................................................... 13
Create an administrative user.................................................................................................... 13
Getting started ................................................................................................................................ 15
Step 1: Create a Lambda function .............................................................................................. 15
Step 2: Create an HTTP API ....................................................................................................... 16
Step 3: Test your API ................................................................................................................ 16
(Optional) Step 4: Clean up....................................................................................................... 17
Next steps............................................................................................................................... 18
Tutorials and workshops................................................................................................................... 19
REST API tutorials.................................................................................................................... 19
Build an API with Lambda integration................................................................................. 20
Tutorial: Create a REST API by importing an example ............................................................ 35
Build an API with HTTP integration .................................................................................... 43
Tutorial: Build an API with private integration ...................................................................... 76
Tutorial: Build an API with AWS integration ......................................................................... 78
Tutorial: Calc API with three integrations ........................................................................... 82
Tutorial: Create a REST API as an Amazon S3 proxy in API Gateway ....................................... 102
Tutorial: Create a REST API as an Amazon Kinesis proxy ....................................................... 128
Build a private REST API................................................................................................. 166
HTTP API tutorials .................................................................................................................. 170
CRUD API with Lambda and DynamoDB............................................................................ 170
Private integration to Amazon ECS ................................................................................... 178
WebSocket API tutorials .......................................................................................................... 183
WebSocket chat app ....................................................................................................... 183
Working with REST APIs .................................................................................................................. 188
Develop................................................................................................................................. 188
Create and configure ....................................................................................................... 188
Access control................................................................................................................ 220
Integrations................................................................................................................... 270
Request validation.......................................................................................................... 312
Data transformations...................................................................................................... 324
Gateway responses......................................................................................................... 370
iii
Amazon API Gateway Developer Guide
CORS ............................................................................................................................ 377
Binary media types ......................................................................................................... 384
Invoke........................................................................................................................... 406
OpenAPI........................................................................................................................ 428
Publish.................................................................................................................................. 438
Deploying a REST API ..................................................................................................... 438
Custom domain names.................................................................................................... 466
Optimize............................................................................................................................... 489
Cache settings................................................................................................................ 489
Content encoding ........................................................................................................... 494
Distribute.............................................................................................................................. 499
Usage plans................................................................................................................... 499
API documentation......................................................................................................... 513
SDK generation.............................................................................................................. 556
Developer portal............................................................................................................ 571
Sell your APIs as SaaS ..................................................................................................... 578
Protect.................................................................................................................................. 581
Mutual TLS.................................................................................................................... 582
Client certificates............................................................................................................ 586
AWS WAF...................................................................................................................... 613
Throttling...................................................................................................................... 615
Private APIs................................................................................................................... 616
Monitor................................................................................................................................. 623
CloudWatch metrics........................................................................................................ 623
CloudWatch logs............................................................................................................ 629
Kinesis Data Firehose ...................................................................................................... 633
X-Ray............................................................................................................................ 634
Working with HTTP APIs ................................................................................................................. 644
Develop................................................................................................................................. 644
Creating an HTTP API ..................................................................................................... 644
Routes........................................................................................................................... 645
Access control................................................................................................................ 647
Integrations................................................................................................................... 655
CORS ............................................................................................................................ 668
Parameter mapping........................................................................................................ 670
OpenAPI........................................................................................................................ 674
Publish.................................................................................................................................. 680
Stages........................................................................................................................... 680
Custom domain names.................................................................................................... 682
Protect.................................................................................................................................. 686
Throttling...................................................................................................................... 686
Mutual TLS.................................................................................................................... 687
Monitor................................................................................................................................. 691
Metrics.......................................................................................................................... 691
Logging......................................................................................................................... 692
Troubleshooting ..................................................................................................................... 698
Lambda integrations....................................................................................................... 699
JWT authorizers............................................................................................................. 700
Working with WebSocket APIs .......................................................................................................... 702
About WebSocket APIs ............................................................................................................ 702
Managing connected users and client apps ........................................................................ 703
Invoking your backend integration .................................................................................... 704
Sending data from backend services to connected clients .................................................... 706
WebSocket selection expressions ...................................................................................... 706
Develop................................................................................................................................. 711
Create and configure ....................................................................................................... 711
Routes........................................................................................................................... 712
iv
Amazon API Gateway Developer Guide
Access control................................................................................................................ 717
Integrations................................................................................................................... 721
Request validation.......................................................................................................... 725
Data transformations...................................................................................................... 725
Binary media types ......................................................................................................... 733
Invoke........................................................................................................................... 733
Publish.................................................................................................................................. 735
Stages........................................................................................................................... 735
Deploy a WebSocket API ................................................................................................. 737
Custom domain names.................................................................................................... 738
Protect.................................................................................................................................. 742
Account-level throttling per Region .................................................................................. 742
Route-level throttling ...................................................................................................... 742
Monitor................................................................................................................................. 743
Metrics.......................................................................................................................... 743
Logging......................................................................................................................... 744
API Gateway ARNs.......................................................................................................................... 748
HTTP API and WebSocket API resources .................................................................................... 748
REST API resources ................................................................................................................. 750
execute-api (HTTP APIs, WebSocket APIs, and REST APIs) ........................................................ 752
OpenAPI extensions........................................................................................................................ 753
x-amazon-apigateway-any-method ..................................................................................... 754
x-amazon-apigateway-any-method examples..................................................................... 754
x-amazon-apigateway-cors....................................................................................................... 755
x-amazon-apigateway-cors example.................................................................................. 755
x-amazon-apigateway-api-key-source.............................................................................. 756
x-amazon-apigateway-api-key-source example................................................................... 756
x-amazon-apigateway-auth................................................................................................ 756
x-amazon-apigateway-auth example................................................................................. 757
x-amazon-apigateway-authorizer ..................................................................................... 757
x-amazon-apigateway-authorizer examples for REST APIs .................................................... 759
x-amazon-apigateway-authorizer examples for HTTP APIs ................................................... 761
x-amazon-apigateway-authtype......................................................................................... 762
x-amazon-apigateway-authtype example........................................................................... 762
See also........................................................................................................................ 764
x-amazon-apigateway-binary-media-type.................................................................................. 764
x-amazon-apigateway-binary-media-types example............................................................ 764
x-amazon-apigateway-documentation....................................................................................... 764
x-amazon-apigateway-documentation example.................................................................. 764
x-amazon-apigateway-endpoint-configuration............................................................................ 765
x-amazon-apigateway-endpoint-configuration examples...................................................... 765
x-amazon-apigateway-gateway-responses.................................................................................. 766
x-amazon-apigateway-gateway-responses example............................................................. 766
x-amazon-apigateway-gateway-responses.gatewayResponse........................................................ 766
x-amazon-apigateway-gateway-responses.gatewayResponse example................................... 767
x-amazon-apigateway-gateway-responses.responseParameters..................................................... 767
x-amazon-apigateway-gateway-responses.responseParameters example................................ 768
x-amazon-apigateway-gateway-responses.responseTemplates...................................................... 768
x-amazon-apigateway-gateway-responses.responseTemplates example................................. 768
x-amazon-apigateway-importexport-version.............................................................................. 769
x-amazon-apigateway-importexport-version example.......................................................... 769
x-amazon-apigateway-integration................................................................................... 769
x-amazon-apigateway-integration examples....................................................................... 772
x-amazon-apigateway-integrations........................................................................................... 773
x-amazon-apigateway-integrations example....................................................................... 774
x-amazon-apigateway-integration.requestTemplates................................................................... 775
x-amazon-apigateway-integration.requestTemplates example.............................................. 775
v
Amazon API Gateway Developer Guide
x-amazon-apigateway-integration.requestParameters.................................................................. 776
x-amazon-apigateway-integration.requestParameters example............................. 777
x-amazon-apigateway-integration.responses.............................................................................. 777
x-amazon-apigateway-integration.responses example............................................ 778
x-amazon-apigateway-integration.response................................................................................ 778
x-amazon-apigateway-integration.response example.............................................. 779
x-amazon-apigateway-integration.responseTemplates................................................................. 780
x-amazon-apigateway-integration.responseTemplate example.............................................. 780
x-amazon-apigateway-integration.responseParameters................................................................ 780
x-amazon-apigateway-integration.responseParameters example........................... 781
x-amazon-apigateway-integration.tlsConfig............................................................................... 781
x-amazon-apigateway-integration.tlsConfig examples......................................................... 782
x-amazon-apigateway-minimum-compression-size...................................................................... 782
x-amazon-apigateway-minimum-compression-size example................................................. 783
x-amazon-apigateway-policy.................................................................................................... 783
x-amazon-apigateway-policy example....................................................................... 783
x-amazon-apigateway-request-validator.................................................................................... 783
x-amazon-apigateway-request-validator example................................................... 784
x-amazon-apigateway-request-validators................................................................................... 784
x-amazon-apigateway-request-validators example................................................. 785
x-amazon-apigateway-request-validators.requestValidator........................................................... 785
x-amazon-apigateway-request-validators.requestValidator example.................. 786
x-amazon-apigateway-tag-value............................................................................................... 786
x-amazon-apigateway-tag-value example.................................................................. 786
Security......................................................................................................................................... 787
Data protection...................................................................................................................... 787
Data encryption............................................................................................................. 788
Internetwork traffic privacy .............................................................................................. 788
Identity and access management .............................................................................................. 789
Audience....................................................................................................................... 789
Authenticating with identities.......................................................................................... 789
Managing access using policies ......................................................................................... 791
How Amazon API Gateway works with IAM ........................................................................ 793
Identity-based policy examples ........................................................................................ 797
Resource-based policy examples ....................................................................................... 802
Troubleshooting............................................................................................................. 802
Using service-linked roles ................................................................................................ 804
Logging and monitoring.......................................................................................................... 807
Working with AWS CloudTrail ........................................................................................... 808
Working with AWS Config ............................................................................................... 810
Compliance validation............................................................................................................. 812
Resilience.............................................................................................................................. 813
Infrastructure security............................................................................................................. 813
Configuration and vulnerability analysis .................................................................................... 813
Best practices......................................................................................................................... 813
Tagging......................................................................................................................................... 815
API Gateway resources that can be tagged ................................................................................ 815
Tag inheritance in the Amazon API Gateway V1 API ............................................................ 816
Tag restrictions and usage conventions ............................................................................. 817
Attribute-based access control ................................................................................................. 817
Example 1: Limit actions based on resource tags ................................................................ 818
Example 2: Limit actions based on tags in the request ......................................................... 818
Example 3: Deny actions based on resource tags ................................................................ 819
Example 4: Allow actions based on resource tags ................................................................ 819
Example 5: Allow actions based on resource tag keys .......................................................... 820
API references................................................................................................................................ 821
Quotas and important notes ............................................................................................................ 822
vi
Amazon API Gateway Developer Guide
API Gateway account-level quotas, per Region ........................................................................... 822
HTTP API quotas .................................................................................................................... 823
.................................................................................................................................... 823
API Gateway quotas for configuring and running a WebSocket API ................................................ 824
API Gateway quotas for configuring and running a REST API ........................................................ 825
API Gateway quotas for creating, deploying and managing an API ................................................ 827
Important notes..................................................................................................................... 828
Important notes for REST and WebSocket APIs .................................................................. 828
Important notes for WebSocket APIs ................................................................................ 829
Important notes for REST APIs ......................................................................................... 829
Document history........................................................................................................................... 833
Earlier updates....................................................................................................................... 838
AWS glossary................................................................................................................................. 844
vii
Amazon API Gateway Developer Guide
Architecture of API Gateway
What is Amazon API Gateway?
Amazon API Gateway is an AWS service for creating, publishing, maintaining, monitoring, and securing
REST, HTTP, and WebSocket APIs at any scale. API developers can create APIs that access AWS or other
web services, as well as data stored in the AWS Cloud. As an API Gateway API developer, you can create
APIs for use in your own client applications. Or you can make your APIs available to third-party app
developers. For more information, see the section called “Who uses API Gateway?” (p. 4).
API Gateway creates RESTful APIs that:
• Are HTTP-based.
• Enable stateless client-server communication.
• Implement standard HTTP methods such as GET, POST, PUT, PATCH, and DELETE.
For more information about API Gateway REST APIs and HTTP APIs, see the section called “Choosing
between REST APIs and HTTP APIs ” (p. 9), Working with HTTP APIs (p. 644), the section called “Use
API Gateway to create REST APIs” (p. 3), and the section called “Create and configure” (p. 188).
API Gateway creates WebSocket APIs that:
• Adhere to the WebSocket protocol, which enables stateful, full-duplex communication between client
and server.
• Route incoming messages based on message content.
For more information about API Gateway WebSocket APIs, see the section called “Use API Gateway to
create WebSocket APIs” (p. 4) and the section called “About WebSocket APIs” (p. 702).
Topics
• Architecture of API Gateway (p. 1)
• Features of API Gateway (p. 2)
• API Gateway use cases (p. 3)
• Accessing API Gateway (p. 5)
• Part of AWS serverless infrastructure (p. 5)
• How to get started with Amazon API Gateway (p. 5)
• Amazon API Gateway concepts (p. 5)
• Choosing between REST APIs and HTTP APIs (p. 9)
Architecture of API Gateway
The following diagram shows API Gateway architecture.
1
Amazon API Gateway Developer Guide
Features of API Gateway
This diagram illustrates how the APIs you build in Amazon API Gateway provide you or your developer
customers with an integrated and consistent developer experience for building AWS serverless
applications. API Gateway handles all the tasks involved in accepting and processing up to hundreds of
thousands of concurrent API calls. These tasks include traffic management, authorization and access
control, monitoring, and API version management.
API Gateway acts as a "front door" for applications to access data, business logic, or functionality from
your backend services, such as workloads running on Amazon Elastic Compute Cloud (Amazon EC2), code
running on AWS Lambda, any web application, or real-time communication applications.
Features of API Gateway
Amazon API Gateway offers features such as the following:
• Support for stateful (WebSocket (p. 702)) and stateless (HTTP (p. 644) and REST (p. 188)) APIs.
• Powerful, flexible authentication (p. 220) mechanisms, such as AWS Identity and Access Management
policies, Lambda authorizer functions, and Amazon Cognito user pools.
• Developer portal (p. 571) for publishing your APIs.
• Canary release deployments (p. 455) for safely rolling out changes.
• CloudTrail (p. 808) logging and monitoring of API usage and API changes.
• CloudWatch access logging and execution logging, including the ability to set alarms. For more
information, see the section called “CloudWatch metrics” (p. 623) and the section called
“Metrics” (p. 743).
• Ability to use AWS CloudFormation templates to enable API creation. For more information, see
Amazon API Gateway Resource Types Reference and Amazon API Gateway V2 Resource Types
Reference.
• Support for custom domain names (p. 466).
• Integration with AWS WAF (p. 613) for protecting your APIs against common web exploits.
• Integration with AWS X-Ray (p. 634) for understanding and triaging performance latencies.
For a complete list of API Gateway feature releases, see Document history (p. 833).
2
Amazon API Gateway Developer Guide
API Gateway use cases
API Gateway use cases
Topics
• Use API Gateway to create REST APIs (p. 3)
• Use API Gateway to create HTTP APIs (p. 3)
• Use API Gateway to create WebSocket APIs (p. 4)
• Who uses API Gateway? (p. 4)
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
• Throttling of HTTP requests
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.
3