ebook img

Amazon API Gateway - Developer Guide PDF

381 Pages·2017·2.32 MB·English
Save to my drive
Quick download
Download
Most books are stored in the elastic cloud where traffic is expensive. For this reason, we have a limit on daily download.

Preview Amazon API Gateway - Developer Guide

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

Description:
Table of Contents. What Is Amazon API Gateway? Get Ready to Use API Gateway . Create an API Using the AWS SDK for API Gateway .
See more

The list of books you might like

Most books are stored in the elastic cloud where traffic is expensive. For this reason, we have a limit on daily download.