docs.aws.amazon.com
Open in
urlscan Pro
54.239.23.208
Public Scan
URL:
https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-known-issues.html
Submission: On August 28 via api from US
Submission: On August 28 via api from US
Form analysis 0 forms found in the DOM
Text Content
SELECT YOUR COOKIE PREFERENCES
We use cookies and similar tools to enhance your experience, provide our
services, deliver relevant advertising, and make improvements. Approved third
parties also use these tools to help us deliver advertising and provide certain
site features.
CustomizeAccept all
CUSTOMIZE COOKIE PREFERENCES
We use cookies and similar tools (collectively, "cookies") for the following
purposes.
ESSENTIAL
Essential cookies are necessary to provide our site and services and cannot be
deactivated. They are usually set in response to your actions on the site, such
as setting your privacy preferences, signing in, or filling in forms.
PERFORMANCE
Performance cookies provide anonymous statistics about how customers navigate
our site so we can improve site experience and performance. Approved third
parties may perform analytics on our behalf, but they cannot use the data for
their own purposes.
Allow performance category
Allowed
FUNCTIONAL
Functional cookies help us provide useful site features, remember your
preferences, and display relevant content. Approved third parties may set these
cookies to provide certain site features. If you do not allow these cookies,
then some or all of these services may not function properly.
Allow functional category
Allowed
ADVERTISING
Advertising cookies may be set through our site by us or our advertising
partners and help us deliver relevant marketing content. If you do not allow
these cookies, you will experience less relevant advertising.
Allow advertising category
Allowed
Blocking some types of cookies may impact your experience of our sites. You may
review and change your choices at any time by clicking Cookie preferences in the
footer of this site. We and selected third-parties use cookies or similar
technologies as specified in the AWS Cookie Notice
.
CancelSave preferences
English
Sign In to the Console
1. AWS
2. ...
3. Documentation
4. Amazon API Gateway
5. Developer Guide
Feedback
Preferences
Amazon API Gateway
Developer Guide
* What is Amazon API Gateway?
* API Gateway use cases
* API Gateway concepts
* Choosing HTTP API or REST API
* API Gateway pricing
* Prerequisites
* Getting started
* Tutorials and workshops
* HTTP API tutorials
* CRUD API with Lambda and DynamoDB
* Private integration to Amazon ECS
* REST API tutorials
* Build an API with Lambda integration
* Tutorial: Hello World API with Lambda proxy integration
* Tutorial: Build an API with cross-account Lambda proxy integration
* Tutorial: Build an API with Lambda non-proxy integration
* Tutorial: Create a REST API by importing an example
* Build an API with HTTP integration
* Tutorial: Build a REST API with HTTP proxy integration
* Tutorial: Build an API with HTTP non-proxy integration
* Tutorial: Build an API with private integration
* Tutorial: Build an API with AWS integration
* Tutorial: Calc API with three integrations
* OpenAPI definitions of a sample API for a Lambda function
* Tutorial: Create a REST API as an Amazon S3 proxy in API Gateway
* OpenAPI definitions of a sample API as an Amazon S3 proxy
* Tutorial: Create a REST API as an Amazon Kinesis proxy
* OpenAPI definitions of a sample API as a Kinesis proxy
* Build a private REST API
* Working with HTTP APIs
* Develop
* Routes
* Access control
* Lambda authorizers
* JWT authorizers
* IAM authorization
* Integrations
* AWS Lambda integrations
* HTTP integrations
* AWS service integrations
* AWS service integrations reference
* Private integrations
* VPC links
* CORS
* Parameter mapping
* OpenAPI
* Export
* Publish
* Stages
* Custom domain names
* API mappings
* Disable the default endpoint
* Protect
* Throttling
* Mutual TLS
* Monitor
* Metrics
* Logging
* Logging variables
* Troubleshooting
* Lambda integrations
* JWT authorizers
* Working with REST APIs
* Develop
* Create and configure
* Choose an API endpoint type
* Change a public or private API endpoint type
* Initialize REST API setup
* Set up an API using the API Gateway console
* Set up an edge-optimized API using AWS CLI commands
* Set up an edge-optimized API using the AWS SDK for Node.js
* Set up an edge-optimized API by importing OpenAPI definitions
* Set up a regional API
* Set up REST API methods
* Set up method request
* Set up method response
* Set up method using the console
* Access control
* Use API Gateway resource policies
* Access policy language overview for Amazon API Gateway
* How resource policies affect authorization workflow
* API Gateway resource policy examples
* Create and attach an API Gateway resource policy to an API
* AWS condition keys that can be used in API Gateway resource
policies
* Use IAM permissions
* Control access for invoking an API
* IAM policy examples for API execution permissions
* Create and attach a policy to an IAM user
* Use VPC endpoint policies for private APIs
* Using tags to control access to a REST API
* Use Lambda authorizers
* Configure a Lambda authorizer using the console
* Input to a Lambda authorizer
* Output from an Amazon API Gateway Lambda authorizer
* Call an API with Lambda authorizers
* Configure a cross-account Lambda authorizer
* Use Amazon Cognito user pool as authorizer for a REST API
* Obtain permissions to create Amazon Cognito user pool authorizers
for a REST API
* Create an Amazon Cognito user pool for a REST API
* Integrate a REST API with an Amazon Cognito user pool
* Call a REST API integrated with a user pool
* Configure cross-account Amazon Cognito authorizer for a REST API
* Integrations
* Integration request
* Basic tasks of an API integration request
* Choose an API integration type
* Set up proxy integrations with a proxy resource
* Set up integration request using the console
* Integration response
* Lambda integration
* Set up Lambda proxy integrations
* Set up Lambda custom integrations
* Set up asynchronous invocation of the backend Lambda function
* Handle Lambda errors in API Gateway
* HTTP integration
* Private integration
* Set up a Network Load Balancer for private integrations
* Grant permissions to create a VPC link
* Set up an API Gateway API with private integrations using the API
Gateway console
* Set up an API with private integrations using AWS CLI
* Set up API with private integrations using OpenAPI
* API Gateway accounts used for private integrations
* Mock integration
* Enable mock integration using the API Gateway console
* Request validation
* Set up basic request validation in API Gateway
* Test basic request validation in API Gateway
* OpenAPI definitions of a sample API with basic request validation
* Data transformations
* Working with models and mapping templates
* Create a model
* Use a mapping template to override an API's request and response
parameters and status codes
* Set up request and response data mappings using the console
* Examples
* Photos example
* News article example
* Sales invoice example
* Employee record example
* Request and response data mapping reference
* Integration passthrough behaviors
* Mapping template and access logging reference
* Gateway responses
* Set up a gateway response for a REST API using the API Gateway
console
* Set up a gateway response using the API Gateway REST API
* Set up gateway response customization in OpenAPI
* Gateway response types
* CORS
* Enable CORS using the console
* Enable CORS using OpenAPI definition
* Testing CORS
* Binary media types
* Content type conversions in API Gateway
* Enabling binary support using the API Gateway console
* Enabling binary support using the API Gateway REST API
* Import and export content encodings
* Examples of binary support
* Return binary media from a Lambda proxy integration
* Access binary files in Amazon S3 through an API Gateway API
* Access binary files in Lambda using an API Gateway API
* Invoke
* Use the console to test a REST API method
* Call REST API through generated SDKs
* Use a Java SDK generated by API Gateway for a REST API
* Use an Android SDK generated by API Gateway for a REST API
* Use a JavaScript SDK generated by API Gateway for a REST API
* Use a Ruby SDK generated by API Gateway for a REST API
* Use iOS SDK generated by API Gateway for a REST API in
Objective-C or Swift
* Use generated iOS SDK (Objective-C) to call API
* Use generated iOS SDK (Swift) to call API
* How to invoke a private API
* OpenAPI
* Import an edge-optimized API
* Import a regional API
* Import an OpenAPI file to update an existing API definition
* Set the OpenAPI basePath property
* AWS variables
* Errors and warnings during import
* Export a REST API
* Publish
* Deploying a REST API
* Deploy a REST API
* Deploy a REST API (console)
* Set up a stage
* Set up a stage using the API Gateway console
* Set up tags
* Set up stage variables
* Set stage variables
* Use stage variables
* Stage variables reference
* Set up a canary release deployment
* Create a canary release deployment
* Update a canary release
* Promote a canary release
* Disable a canary release
* Redeploying a REST API
* Custom domain names
* Getting certificates ready in AWS Certificate Manager
* Choosing a minimum TLS version
* Creating an edge-optimized custom domain name
* Setting up a regional custom domain name
* Migrating custom domain names
* API mappings
* Disable the default endpoint
* Optimize
* Cache settings
* Content encoding
* Enable payload compression for an API
* Call a method with a compressed payload
* Receive a response with a compressed payload
* Distribute
* Usage plans
* Steps to configure a usage plan
* Choose an API key source
* Set up API keys using the API Gateway console
* Create, configure, and test usage plans with the API Gateway console
* Set up API keys using the API Gateway REST API
* Create, configure, and test usage plans using the API Gateway CLI
and REST API
* API Gateway API key file format
* API documentation
* Representation of API documentation in API Gateway
* Document an API using the API Gateway console
* Publish API documentation using the API Gateway console
* Document an API using the API Gateway REST API
* Publish API documentation using the API Gateway REST API
* Import API documentation
* Control access to API documentation
* SDK generation
* Generate SDKs for an API using the API Gateway console
* Generate the Java SDK of an API
* Generate the Android SDK of an API
* Generate the iOS SDK of an API
* Generate the JavaScript SDK of a REST API
* Generate the Ruby SDK of an API
* Generate SDKs for an API using AWS CLI commands
* Simple calculator Lambda function
* Simple calculator API in API Gateway
* Simple calculator API OpenAPI definition
* Developer portal
* Sell your APIs as SaaS
* Protect
* Mutual TLS
* Client certificates
* Supported certificate authorities for HTTP and HTTP proxy
integration
* AWS WAF
* Throttling
* Private APIs
* Monitor
* CloudWatch metrics
* Amazon API Gateway dimensions and metrics
* View metrics with the API dashboard
* View metrics in the CloudWatch console
* View log event in the CloudWatch console
* Monitoring tools in AWS
* CloudWatch logs
* Kinesis Data Firehose
* X-Ray
* Setting up AWS X-Ray
* Using AWS X-Ray service maps and trace views
* Configuring AWS X-Ray sampling rules
* Understanding X-Ray traces
* Working with WebSocket APIs
* About WebSocket APIs
* Managing connected users and client apps
* Invoking your backend integration
* Sending data from backend services to connected clients
* WebSocket selection expressions
* Develop
* Create and configure
* Routes
* Set up WebSocket API route responses
* Subprotocol support
* Access control
* Using IAM authorization
* Creating a Lambda REQUEST authorizer function
* Integrations
* Integration request
* Integration responses
* Request validation
* Data transformations
* Data mapping
* WebSocket mapping template reference
* Binary media types
* Invoke
* Use wscat to connect to a WebSocket API and send messages to it
* Use @connections commands in your backend service
* Publish
* Deploy a WebSocket API
* Custom domain names
* API mappings
* Disable the default endpoint
* Protect
* Monitor
* Metrics
* Logging
* API Gateway ARNs
* OpenAPI extensions
* x-amazon-apigateway-any-method
* x-amazon-apigateway-cors
* x-amazon-apigateway-api-key-source
* x-amazon-apigateway-auth
* x-amazon-apigateway-authorizer
* x-amazon-apigateway-authtype
* x-amazon-apigateway-binary-media-type
* x-amazon-apigateway-documentation
* x-amazon-apigateway-endpoint-configuration
* x-amazon-apigateway-gateway-responses
* x-amazon-apigateway-gateway-responses.gatewayResponse
* x-amazon-apigateway-gateway-responses.responseParameters
* x-amazon-apigateway-gateway-responses.responseTemplates
* x-amazon-apigateway-importexport-version
* x-amazon-apigateway-integration
* x-amazon-apigateway-integrations
* x-amazon-apigateway-integration.requestTemplates
* x-amazon-apigateway-integration.requestParameters
* x-amazon-apigateway-integration.responses
* x-amazon-apigateway-integration.response
* x-amazon-apigateway-integration.responseTemplates
* x-amazon-apigateway-integration.responseParameters
* x-amazon-apigateway-integration.tlsConfig
* x-amazon-apigateway-minimum-compression-size
* x-amazon-apigateway-policy
* x-amazon-apigateway-request-validator
* x-amazon-apigateway-request-validators
* x-amazon-apigateway-request-validators.requestValidator
* x-amazon-apigateway-tag-value
* Security
* Data protection
* Data encryption
* Internetwork traffic privacy
* Identity and access management
* How Amazon API Gateway works with IAM
* Identity-based policy examples
* Resource-based policy examples
* Troubleshooting
* Using service-linked roles
* Logging and monitoring
* Working with AWS CloudTrail
* Working with AWS Config
* Compliance validation
* Resilience
* Infrastructure security
* Configuration and vulnerability analysis
* Best practices
* Tagging
* API Gateway resources that can be tagged
* Tag-based access control
* API references
* Quotas and important notes
* Important notes
* Document history
* AWS glossary
Amazon API Gateway important notes - Amazon API Gateway
AWSDocumentationAmazon API GatewayDeveloper Guide
Important notes for REST and WebSocket APIsImportant notes for WebSocket
APIsImportant notes for REST APIs
AMAZON API GATEWAY IMPORTANT NOTES
PDF
Kindle
RSS
Topics
* Amazon API Gateway important notes for REST and WebSocket APIs
* Amazon API Gateway important notes for WebSocket APIs
* Amazon API Gateway important notes for REST APIs
AMAZON API GATEWAY IMPORTANT NOTES FOR REST AND WEBSOCKET APIS
* API Gateway does not support sharing a custom domain name across REST and
WebSocket APIs.
* Stage names can only contain alphanumeric characters, hyphens, and
underscores. Maximum length is 128 characters.
* The /ping and /sping paths are reserved for the service health check. Use of
these for API root-level resources with custom domains will fail to produce
the expected result.
* API Gateway currently limits log events to 1024 bytes. Log events larger than
1024 bytes, such as request and response bodies, will be truncated by API
Gateway before submission to CloudWatch Logs.
* CloudWatch Metrics currently limits dimension names and values to 255 valid
XML characters. (For more information, see the CloudWatch User Guide.)
Dimension values are a function of user-defined names, including API name,
label (stage) name, and resource name. When choosing these names, be careful
not to exceed CloudWatch Metrics limits.
* The maximum size of a mapping template is 300 KB.
AMAZON API GATEWAY IMPORTANT NOTES FOR WEBSOCKET APIS
* API Gateway supports message payloads up to 128 KB with a maximum frame size
of 32 KB. If a message exceeds 32 KB, you must split it into multiple frames,
each 32 KB or smaller. If a larger message is received, the connection is
closed with code 1009.
AMAZON API GATEWAY IMPORTANT NOTES FOR REST APIS
* The plain text pipe character (|) is not supported for any request URL query
string and must be URL-encoded.
* The semicolon character (;) is not supported for any request URL query string
and results in the data being split.
* When using the API Gateway console to test an API, you may get an "unknown
endpoint errors" response if a self-signed certificate is presented to the
backend, the intermediate certificate is missing from the certificate chain,
or any other unrecognizable certificate-related exceptions thrown by the
backend.
* For an API Resource or Method entity with a private integration, you should
delete it after removing any hard-coded reference of a VpcLink. Otherwise,
you have a dangling integration and receive an error stating that the VPC
link is still in use even when the Resource or Method entity is deleted. This
behavior does not apply when the private integration references VpcLink
through a stage variable.
* The following backends may not support SSL client authentication in a way
that's compatible with API Gateway:
* NGINX
* Heroku
* API Gateway supports most of the OpenAPI 2.0 specification and the OpenAPI
3.0 specification, with the following exceptions:
* Path segments can only contain alphanumeric characters, hyphens, periods,
commas, colons, and curly braces. Path parameters must be separate path
segments. For example, "resource/{path_parameter_name}" is valid;
"resource{path_parameter_name}" is not.
* Model names can only contain alphanumeric characters.
* For input parameters, only the following attributes are supported: name,
in, required, type, description. Other attributes are ignored.
* The securitySchemes type, if used, must be apiKey. However, OAuth 2 and
HTTP Basic authentication are supported via Lambda authorizers; the
OpenAPI configuration is achieved via vendor extensions.
* The deprecated field is not supported and is dropped in exported APIs.
* API Gateway models are defined using JSON schema draft 4, instead of the
JSON schema used by OpenAPI.
* The discriminator parameter is not supported in any schema object.
* The example tag is not supported.
* exclusiveMinimum is not supported by API Gateway.
* The maxItems and minItems tags are not included in simple request
validation. To work around this, update the model after import before
doing validation.
* oneOf is not supported by API Gateway.
* The readOnly field is not supported.
* Response definitions of the "500": {"$ref": "#/responses/UnexpectedError"}
form is not supported in the OpenAPI document root. To work around this,
replace the reference by the inline schema.
* Numbers of the Int32 or Int64 type are not supported. An example is shown
as follows:
"elementId": {
"description": "Working Element Id",
"format": "int32",
"type": "number"
}
* Decimal number format type ("format": "decimal") is not supported in a
schema definition.
* In method responses, schema definition must be of an object type and
cannot be of primitive types. For example, "schema": { "type": "string"}
is not supported. However, you can work around this using the following
object type:
"schema": {
"$ref": "#/definitions/StringResponse"
}
"definitions": {
"StringResponse": {
"type": "string"
}
}
* API Gateway doesn't use root level security defined in the OpenAPI
specification. Hence security needs to be defined at an operation level to
be appropriately applied.
* The default keyword is not supported.
* API Gateway enacts the following restrictions and limitations when handling
methods with either Lambda integration or HTTP integration.
* Header names and query parameters are processed in a case-sensitive way.
* The following table lists the headers that may be dropped, remapped, or
otherwise modified when sent to your integration endpoint or sent back by
your integration endpoint. In this table:
* Remapped means that the header name is changed from <string> to
X-Amzn-Remapped-<string>.
Remapped Overwritten means that the header name is changed from
<string> to X-Amzn-Remapped-<string> and the value is overwritten.
Header name Request (http/http_proxy/lambda) Response
(http/http_proxy/lambda) Age Passthrough Passthrough Accept Passthrough
Dropped/Passthrough/Passthrough Accept-Charset Passthrough Passthrough
Accept-Encoding Passthrough Passthrough Authorization Passthrough *
Remapped Connection Passthrough/Passthrough/Dropped Remapped
Content-Encoding Passthrough/Dropped/Passthrough Passthrough
Content-Length Passthrough (generated based on body) Passthrough
Content-MD5 Dropped Remapped Content-Type Passthrough Passthrough Date
Passthrough Remapped Overwritten Expect Dropped Dropped Host Overwritten
to the integration endpoint Dropped Max-Forwards Dropped Remapped Pragma
Passthrough Passthrough Proxy-Authenticate Dropped Dropped Range
Passthrough Passthrough Referer Passthrough Passthrough Server Dropped
Remapped Overwritten TE Dropped Dropped Transfer-Encoding
Dropped/Dropped/Exception Dropped Trailer Dropped Dropped Upgrade Dropped
Dropped User-Agent Passthrough Remapped Via Dropped/Dropped/Passthrough
Passthrough/Dropped/Dropped Warn Passthrough Passthrough WWW-Authenticate
Dropped Remapped
* The Authorization header is dropped if it contains a Signature Version 4
signature.
* The Android SDK of an API generated by API Gateway uses the
java.net.HttpURLConnection class. This class will throw an unhandled
exception, on devices running Android 4.4 and earlier, for a 401 response
resulted from remapping of the WWW-Authenticate header to
X-Amzn-Remapped-WWW-Authenticate.
* Unlike API Gateway-generated Java, Android and iOS SDKs of an API, the
JavaScript SDK of an API generated by API Gateway does not support retries
for 500-level errors.
* The test invocation of a method uses the default content type of
application/json and ignores specifications of any other content types.
* When sending requests to an API by passing the X-HTTP-Method-Override header,
API Gateway overrides the method. So in order to pass the header to the
backend, the header needs to be added to the integration request.
* When a request contains multiple media types in its Accept header, API
Gateway only honors the first Accept media type. In the situation where you
cannot control the order of the Accept media types and the media type of your
binary content is not the first in the list, you can add the first Accept
media type in the binaryMediaTypes list of your API, API Gateway will return
your content as binary. For example, to send a JPEG file using an <img>
element in a browser, the browser might send
Accept:image/webp,image/*,*/*;q=0.8 in a request. By adding image/webp to the
binaryMediaTypes list, the endpoint will receive the JPEG file as binary.
* Customizing the default gateway response for 413 REQUEST_TOO_LARGE isn't
currently supported.
© 2021, Amazon Web Services, Inc. or its affiliates. All rights reserved.
Thanks for your vote. To provide details, send feedback.
This page is helpful.
Thanks for your vote. To provide details, send feedback.
This page is not helpful.
Javascript is disabled or is unavailable in your browser.
To use the Amazon Web Services Documentation, Javascript must be enabled. Please
refer to your browser's Help pages for instructions.
Document Conventions
Quotas and important notes
Document history
Did this page help you?
Yes No
Did this page help you? - Yes
Thanks for letting us know we're doing a good job!
If you've got a moment, please tell us what we did right so we can do more of
it.
Feedback
Did this page help you? - No
Thanks for letting us know this page needs work. We're sorry we let you down.
If you've got a moment, please tell us how we can make the documentation better.
Feedback
Provide feedback
Edit this page on GitHub
Previous topic: Quotas and important notes
Next topic: Document history
Need help?
* Try the forums
* Connect with an AWS IQ expert
Privacy
Site terms
Cookie preferences
© 2021, Amazon Web Services, Inc. or its affiliates. All rights reserved.
Did this page help you? - Yes
Thanks for letting us know we're doing a good job!
If you've got a moment, please tell us what we did right so we can do more of
it.
Feedback
Did this page help you? - No
Thanks for letting us know this page needs work. We're sorry we let you down.
If you've got a moment, please tell us how we can make the documentation better.
Feedback
On this page
* Important notes for REST and WebSocket APIs
* Important notes for WebSocket APIs
* Important notes for REST APIs