Amazon API Gateway Developer Guide Amazon API Gateway Developer Guide Amazon API Gateway: Developer Guide Copyright © 2018 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 Gateway to AWS Cloud and Beyond ............................................................................................. 1 Part of AWS Serverless Infrastructure ................................................................................... 2 Developer Experiences................................................................................................................ 2 Create and Manage an API Gateway API ............................................................................... 2 Calling an API Gateway API ................................................................................................. 3 Benefits of API Gateway ............................................................................................................. 3 API Gateway Concepts ................................................................................................................ 3 Getting Started .................................................................................................................................. 6 Get Ready to Build API Gateway API ............................................................................................ 6 Sign up for an AWS Account ............................................................................................... 6 Create IAM Users, Groups, Roles, and Policies in Your AWS Account .......................................... 7 Create IAM Policies to Configure API Gateway Resources and to Call a Deployed API .................... 7 Next Step.......................................................................................................................... 9 Build an API from an Example ..................................................................................................... 9 Create and Test an Example API in the Console .................................................................... 10 Next Step........................................................................................................................ 17 See Also.......................................................................................................................... 18 Build an API with Lambda Integration......................................................................................... 18 Build an API with Lambda Proxy Integration ........................................................................ 19 Build an API with Lambda Custom Integration..................................................................... 27 Build an API with HTTP Integrations .......................................................................................... 36 Build an API with HTTP Proxy Integration ........................................................................... 37 Build an API with HTTP Custom Integration ......................................................................... 42 Build an API with Private Integration.......................................................................................... 72 Build an API with AWS Integration............................................................................................. 73 Prerequisites.................................................................................................................... 74 Step 1: Create the Resource ............................................................................................... 74 Step 2: Create the GET Method .......................................................................................... 75 Step 3: Create the AWS Service Proxy Execution Role ............................................................ 75 Step 4: Specify Method Settings and Test the Method .......................................................... 76 Step 5: Deploy the API ...................................................................................................... 77 Step 6: Test the API ......................................................................................................... 77 Step 7: Clean Up.............................................................................................................. 78 Creating an API................................................................................................................................ 79 Choose an Endpoint Type to Set up an API .................................................................................. 79 Initialize API Setup................................................................................................................... 80 Set up an API Using the API Gateway Console ..................................................................... 80 Set up an Edge-Optimized API Using AWS CLI Commands ..................................................... 81 Set up an Edge-Optimized API Using the AWS SDK for Node.js .............................................. 85 Set up an Edge-Optimized API Using the API Gateway REST API ............................................. 92 Set up an Edge-Optimized API by Importing Swagger Definitions ........................................... 99 Set up a Regional API ..................................................................................................... 101 Set up API Methods................................................................................................................ 104 Set up Method Request ................................................................................................... 105 Set up Method Response ................................................................................................. 111 Set up Method Using the Console.................................................................................... 113 Set up API Integrations........................................................................................................... 116 Set up Integration Request .............................................................................................. 117 Set up Integration Response ............................................................................................ 123 Set up Lambda Integrations............................................................................................ 124 Set up HTTP Integrations ............................................................................................... 140 Set up Private Integrations.............................................................................................. 144 Set up Mock Integrations................................................................................................ 150 iii Amazon API Gateway Developer Guide Set up Gateway Responses ...................................................................................................... 153 Gateway Responses in API Gateway .................................................................................. 154 Gateway Response Types ................................................................................................. 154 Set up a Gateway Response Using the API Gateway Console ................................................ 157 Set up a Gateway Response Using the API Gateway REST API ............................................... 159 Set up Gateway Response Customization in Swagger .......................................................... 159 Set up Data Mappings............................................................................................................. 160 Set up Request and Response Data Mappings Using the Console ........................................... 160 Create Models and Mapping Templates ............................................................................. 162 Request and Response Data Mapping Reference ................................................................. 185 Mapping Template Reference ........................................................................................... 189 Support Binary Payloads ........................................................................................................ 196 Content Type Conversions in API Gateway ......................................................................... 197 Enable Binary Support Using the API Gateway Console ....................................................... 200 Enable Binary Support Using API Gateway REST API ........................................................... 203 Import and Export Content Encodings ............................................................................... 207 Examples of Binary Support ............................................................................................. 207 Enable Payload Compression .................................................................................................... 214 Enable Compression for an API ........................................................................................ 214 Call a Method with a Compressed Payload ......................................................................... 216 Receive a Response with a Compressed Payload ................................................................. 217 Enable Request Validation ....................................................................................................... 218 Overview of Basic Request Validation in API Gateway .......................................................... 219 Set up Basic Request Validation in API Gateway ................................................................. 219 Test Basic Request Validation in API Gateway ..................................................................... 223 Swagger Definitions of a Sample API with Basic Request Validation ....................................... 227 Update and Maintain an API.................................................................................................... 230 Update an API Endpoint Type .......................................................................................... 230 Maintain an API Using the Console................................................................................... 232 Import an API ........................................................................................................................ 234 Import an Edge-Optimized API ......................................................................................... 234 Import a Regional API ..................................................................................................... 236 Import a Swagger File to Update an Existing API Definition .................................................. 236 Set the Swagger basePath Property................................................................................ 237 Errors and Warnings during Import ................................................................................... 239 Controlling Access to an API ............................................................................................................ 240 Use IAM Permissions ............................................................................................................... 240 API Gateway Permissions Model for Creating and Managing an API ...................................... 240 API Gateway Permissions Model for Invoking an API .......................................................... 241 Control Access for Managing an API ................................................................................. 242 Control Access for Invoking an API .................................................................................. 244 IAM Policy Examples for Managing API Gateway APIs .......................................................... 247 IAM Policy Examples for API Execution Permissions ............................................................. 251 Create and Attach a Policy to an IAM User ......................................................................... 252 Enable CORS for a Resource .................................................................................................... 253 Prerequisites.................................................................................................................. 254 Enable CORS Using the Console ....................................................................................... 254 Enable CORS Using Swagger Definition ............................................................................. 256 Use Custom Authorizers .......................................................................................................... 258 Types of API Gateway Custom Authorizers ......................................................................... 259 Create a Custom Authorizer Lambda Function .................................................................... 259 Input to a Custom Authorizer ........................................................................................... 262 Output from an Amazon API Gateway Custom Authorizer .................................................... 264 Configure Custom Authorizer ........................................................................................... 265 Call an API with Custom Authorizers ................................................................................. 267 Use Amazon Cognito User Pools ............................................................................................... 270 Obtain Permissions to Create User Pool Authorizers ............................................................ 271 iv Amazon API Gateway Developer Guide Create an Amazon Cognito User Pool ................................................................................ 272 Integrate an API with a User Pool ..................................................................................... 273 Call an API Integrated with a User Pool ............................................................................. 277 Use Client-Side SSL Certificates ................................................................................................ 277 Generate a Client Certificate Using the API Gateway Console ............................................... 278 Configure an API to Use SSL Certificates ........................................................................... 278 Test Invoke.................................................................................................................... 279 Configure Backend to Authenticate API ............................................................................. 281 Supported Certificate Authorities for HTTP and HTTP Proxy Integration ........................................ 281 Use API Gateway Usage Plans .................................................................................................. 297 What Is a Usage Plan?.................................................................................................... 297 Expose API Key Source .................................................................................................... 298 How to Configure a Usage Plan? ...................................................................................... 299 Set Up API Keys Using the API Gateway Console ................................................................ 300 Create, Configure, and Test Usage Plans with the API Gateway Console .................................. 302 Set Up API Keys Using the API Gateway REST API ............................................................... 306 Create, Configure, and Test Usage Plans Using the API Gateway REST API .............................. 307 API Gateway API Key File Format ...................................................................................... 309 Documenting an API....................................................................................................................... 311 Representation of API Documentation in API Gateway ................................................................. 311 Documentation Parts...................................................................................................... 311 Documentation Versions.................................................................................................. 318 Document an API Using the API Gateway Console ..................................................................... 319 Document the API Entity................................................................................................ 319 Document a RESOURCE Entity.......................................................................................... 322 Document a METHOD Entity.............................................................................................. 322 Document a QUERY_PARAMETER Entity............................................................................. 323 Document a PATH_PARAMETER Entity............................................................................... 324 Document a REQUEST_HEADER Entity.............................................................................. 324 Document a REQUEST_BODY Entity................................................................................... 325 Document a RESPONSE Entity.......................................................................................... 325 Document a RESPONSE_HEADER Entity............................................................................. 325 Document a RESPONSE_BODY Entity................................................................................. 326 Document a MODEL Entity............................................................................................... 326 Document an AUTHORIZER Entity.................................................................................... 327 Document an API Using the API Gateway REST API .................................................................... 327 Document the API Entity................................................................................................ 328 Document a RESOURCE Entity.......................................................................................... 329 Document a METHOD Entity.............................................................................................. 331 Document a QUERY_PARAMETER Entity............................................................................. 334 Document a PATH_PARAMETER Entity............................................................................... 335 Document a REQUEST_BODY Entity................................................................................... 335 Document a REQUEST_HEADER Entity............................................................................... 336 Document a RESPONSE Entity.......................................................................................... 337 Document a RESPONSE_HEADER Entity............................................................................. 338 Document an AUTHORIZER Entity.................................................................................... 339 Document a MODEL Entity............................................................................................... 340 Update Documentation Parts ........................................................................................... 342 List Documentation Parts ................................................................................................ 342 Publish API Documentation..................................................................................................... 342 Create a Documentation Snapshot and Associate it with an API Stage ................................... 343 Create a Documentation Snapshot .................................................................................... 343 Update a Documentation Snapshot.................................................................................. 344 Get a Documentation Snapshot........................................................................................ 344 Associate a Documentation Snapshot with an API Stage...................................................... 344 Download a Documentation Snapshot Associated with a Stage ............................................. 345 Import API Documentation ...................................................................................................... 348 v Amazon API Gateway Developer Guide Importing Documentation Parts Using the API Gateway REST API ......................................... 348 Importing Documentation Parts Using the API Gateway Console ........................................... 350 Control Access to API Documentation ....................................................................................... 350 Deploying an API ............................................................................................................................ 352 Create a Deployment .............................................................................................................. 353 Create a Deployment Using AWS CLI ................................................................................. 353 Deploy API from the Console ........................................................................................... 354 Set up a Stage....................................................................................................................... 355 Set up a Stage Using the API Gateway Console .................................................................. 355 Throttle API Requests ..................................................................................................... 358 Enable API Caching......................................................................................................... 360 Set up API Logging......................................................................................................... 364 Set up Stage Variables .................................................................................................... 367 Set Up Tags for an API Stage ........................................................................................... 377 Set up a Canary Release Deployment ........................................................................................ 379 Canary Release Deployment in API Gateway ...................................................................... 380 Create a Canary Release Deployment ................................................................................ 381 Update a Canary Release ................................................................................................. 388 Promote a Canary Release ............................................................................................... 390 Disable a Canary Release ................................................................................................. 394 Export an API ......................................................................................................................... 396 Request to Export an API ................................................................................................ 396 Download API Swagger Definition in JSON ........................................................................ 396 Download API Swagger Definition in YAML ........................................................................ 397 Download API Swagger Definition with Postman Extensions in JSON ..................................... 397 Download API Swagger Definition with API Gateway Integration in YAML ............................... 397 Export API Using the API Gateway Console ........................................................................ 397 Generate SDK of an API.......................................................................................................... 398 Generate SDKs for an API Using the API Gateway Console ................................................... 398 Generate SDKs for an API Using AWS CLI Commands .......................................................... 401 Simple Calculator Lambda Function .................................................................................. 402 Simple Calculator API in API Gateway ............................................................................... 404 Simple Calculator API Swagger Definition .......................................................................... 409 Set up an API Custom Domain Name........................................................................................ 414 Get Certificates Ready in AWS Certificate Manager ............................................................. 416 How to Create an Edge-Optimized Custom Domain Name ................................................... 418 Set up a Regional Custom Domain Name .......................................................................... 424 Migrate Custom Domain Names....................................................................................... 429 Sell Your API as SaaS .............................................................................................................. 435 Initialize AWS Marketplace Integration with API Gateway ..................................................... 435 Handle Customer Subscription to Usage Plans................................................................... 437 Invoking an API .............................................................................................................................. 439 Obtain an API's Invoke URL in the API Gateway Console .............................................................. 439 Use the Console to Test a Method ............................................................................................ 440 Prerequisites.................................................................................................................. 440 Test a Method with the API Gateway Console .................................................................... 440 Use Postman to Call an API ..................................................................................................... 441 Call API through Generated SDKs ............................................................................................. 441 Use a Java SDK Generated by API Gateway ........................................................................ 442 Use an Android SDK Generated by API Gateway ................................................................. 445 Use a JavaScript SDK Generated by API Gateway ................................................................ 446 Use a Ruby SDK Generated by API Gateway ....................................................................... 448 Use iOS SDK Generated by API Gateway in Objective-C or Swift ............................................ 450 Trace API Management and Invocation ...................................................................................... 459 Log API Management Calls with CloudTrail ........................................................................ 459 Monitor API execution with Amazon CloudWatch ................................................................ 461 Swagger Extensions........................................................................................................................ 466 vi Amazon API Gateway Developer Guide x-amazon-apigateway-any-method..................................................................................... 466 x-amazon-apigateway-any-method Example...................................................................... 467 x-amazon-apigateway-api-key-source.............................................................................. 467 x-amazon-apigateway-api-key-source Example................................................................... 467 x-amazon-apigateway-authorizer..................................................................................... 468 x-amazon-apigateway-authorizer Examples........................................................................ 469 x-amazon-apigateway-authtype......................................................................................... 471 x-amazon-apigateway-authtype Example........................................................................... 471 See Also........................................................................................................................ 471 x-amazon-apigateway-binary-media-type.................................................................................. 471 x-amazon-apigateway-binary-media-types Example............................................................ 471 x-amazon-apigateway-documentation....................................................................................... 472 x-amazon-apigateway-documentation Example.................................................................. 472 x-amazon-apigateway-gateway-responses.................................................................................. 472 x-amazon-apigateway-gateway-responses Example............................................................. 473 x-amazon-apigateway-gateway-responses.gatewayResponse........................................................ 473 x-amazon-apigateway-gateway-responses.gatewayResponse Example................................... 474 x-amazon-apigateway-gateway-responses.responseParameters..................................................... 474 x-amazon-apigateway-gateway-responses.repsonseParameters Example................................ 474 x-amazon-apigateway-gateway-responses.responseTemplates...................................................... 475 x-amazon-apigateway-gateway-responses.responseTemplates Example................................. 475 x-amazon-apigateway-integration................................................................................... 475 x-amazon-apigateway-integration Example........................................................................ 478 x-amazon-apigateway-integration.requestTemplates................................................................... 479 x-amazon-apigateway-integration.requestTemplates Example.............................................. 479 x-amazon-apigateway-integration.requestParameters.................................................................. 479 x-amazon-apigateway-integration.requestParameters Example............................. 480 x-amazon-apigateway-integration.responses.............................................................................. 480 x-amazon-apigateway-integration.responses Example............................................ 481 x-amazon-apigateway-integration.response................................................................................ 481 x-amazon-apigateway-integration.response Example.............................................. 482 x-amazon-apigateway-integration.responseTemplates................................................................. 482 x-amazon-apigateway-integration.responseTemplate Example.............................................. 483 x-amazon-apigateway-integration.responseParameters................................................................ 483 x-amazon-apigateway-integration.responseParameters Example............................ 483 x-amazon-apigateway-request-validator.................................................................................... 484 x-amazon-apigateway-request-validator Example................................................... 484 x-amazon-apigateway-request-validators................................................................................... 484 x-amazon-apigateway-request-validators Example.................................................. 485 x-amazon-apigateway-request-validators.requestValidator........................................................... 485 x-amazon-apigateway-request-validators.requestValidator Example.................. 486 Samples and Tutorials ..................................................................................................................... 487 Create an API for Lambda Functions ......................................................................................... 487 Set Up an IAM Role and Policy for an API to Invoke Lambda Functions ................................... 489 Create a Lambda Function in the Backend ......................................................................... 489 Create API Resources for the Lambda Function ................................................................... 491 Create a GET Method with Query Parameters to Call the Lambda Function ............................ 491 Create a POST Method with a JSON Payload to Call the Lambda Function ............................. 495 Create a GET Method with Path Parameters to Call the Lambda Function .............................. 497 Swagger Definitions of a Sample API for a Lambda Function ................................................ 501 Create an API as an Amazon S3 Proxy ....................................................................................... 505 Set Up IAM Permissions for the API to Invoke Amazon S3 Actions ......................................... 506 Create API Resources to Represent Amazon S3 Resources .................................................... 507 Expose an API Method to List the Caller's Amazon S3 Buckets .............................................. 508 Expose API Methods to Access an Amazon S3 Bucket .......................................................... 514 Expose API Methods to Access an Amazon S3 Object in a Bucket .......................................... 517 Call the API Using a REST API Client................................................................................. 520 vii Amazon API Gateway Developer Guide Swagger Definitions of a Sample API as an Amazon S3 Proxy ............................................... 522 Create an API as an Amazon Kinesis Proxy ................................................................................. 531 Create an IAM Role and Policy for the API to Access Kinesis ................................................. 532 Start to Create an API as a Kinesis Proxy ........................................................................... 533 List Streams in Kinesis .................................................................................................... 534 Create, Describe, and Delete a Stream in Kinesis ................................................................. 538 Get Records from and Add Records to a Stream in Kinesis .................................................... 543 Swagger Definitions of a Sample API as a Kinesis Proxy ....................................................... 554 API Gateway REST API .................................................................................................................... 561 Limits, Pricing and Known Issues ...................................................................................................... 562 API Gateway Limits ................................................................................................................. 562 API Gateway Limits for Configuring and Running an API ...................................................... 562 API Gateway Limits for Creating, Deploying and Managing an API ......................................... 563 API Gateway Pricing ................................................................................................................ 564 Known Issues......................................................................................................................... 565 Document History.......................................................................................................................... 568 AWS Glossary................................................................................................................................. 573 viii Amazon API Gateway Developer Guide Gateway to AWS Cloud and Beyond What Is Amazon API Gateway? Amazon API Gateway is an AWS service that enables developers to create, publish, maintain, monitor, and secure APIs at any scale. You can create APIs that access AWS or other web services, as well as data stored in the AWS Cloud. Topics • Gateway to AWS Cloud and Beyond (p. 1) • Developer Experiences (p. 2) • Benefits of API Gateway (p. 3) • Amazon API Gateway Concepts (p. 3) Gateway to AWS Cloud and Beyond API Gateway can be considered a backplane in the cloud to connect AWS services and other public or private websites. It provides consistent RESTful application programming interfaces (APIs) for mobile and web applications to access AWS services. The following diagram shows API Gateway architecture. In practical terms, API Gateway lets you create, configure, and host a RESTful API to enable applications to access the AWS Cloud. For example, an application can call an API in API Gateway to upload a user's annual income and expense data to Amazon S3 or Amazon DynamoDB, process the data in AWS Lambda to compute tax owed, and file a tax return via the IRS website. As shown in the diagram, an app (or client) gains programmatic access to AWS services, or a website on the internet, through one or more APIs, which are hosted in API Gateway. The app is at the API's 1 Amazon API Gateway Developer Guide Part of AWS Serverless Infrastructure frontend. The integrated AWS services and websites are located at the API's backend. In API Gateway, the frontend is encapsulated by method requests and method responses, and the backend is encapsulated by integration requests and integration responses. With Amazon API Gateway, you can build an API to provide your users with an integrated and consistent developer experience to build AWS cloud-based applications. 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 the required services and expose the Lambda functions through API methods in API Gateway. AWS Lambda runs the code on a highly available computing infrastructure. It performs the necessary execution and administration of the computing resources. To enable the serverless applications, API Gateway supports streamlined proxy integrations (p. 120) with AWS Lambda and HTTP endpoints. Developer Experiences There are two kinds of developers who use API Gateway: an app developer and an API developer. The app developer builds a functioning application to call AWS services through API Gateway. The 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. The app developer does not need to have an AWS account, provided that the API does not require IAM permissions or supports authorization of users from third-party identity providers supported by Amazon Cognito identity federation. Such identity providers include Amazon, Amazon Cognito user pool, Facebook, and Google. Create and Manage an API Gateway API An API developer works with the API Gateway service component, named apigateway, to create, configure, and deploy an API. Each API includes a set of resources and methods. A resource is a logical entity that an app can access through a resource path. For example, /incomes is the path of the 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, the POST /incomes method adds an income earned by the caller, and the GET / expenses method queries the reported expenses incurred by the caller. A method corresponds to a REST API request that is submitted by the user of your API and the response returned to the user. The app does not need to know where the requested data is stored and fetched from. The API interfaces with the backend using the integration request or integration response. 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. As an API developer, you can create and manage an API by using the API Gateway console, described in Getting Started with Amazon API Gateway (p. 6), or by calling the API Gateway REST API (p. 561). There are several ways to call this API. They include using the AWS Command-Line Interface (CLI), or by using an AWS SDK. You can also use a REST API client, such as Postman, to make raw API calls. In 2