# OpenAPI extensions for API Gateway
The API Gateway extensions support the AWS-specific authorization and API Gateway-specific API integrations for REST APIs and HTTP APIs. In this section, we describe the API Gateway extensions to the OpenAPI specification.
**Tip**
To understand how the API Gateway extensions are used in an application, you can use the API Gateway console to create a REST API or HTTP API and export it to an OpenAPI definition file. For more information on how to export an API, see [Export a REST API from API Gateway](api-gateway-export-api.md) and [Export HTTP APIs from API Gateway](http-api-export.md).
**Topics**
+ [
# x-amazon-apigateway-any-method object
](api-gateway-swagger-extensions-any-method.md)
+ [
# x-amazon-apigateway-cors object
](api-gateway-swagger-extensions-cors-configuration.md)
+ [
# x-amazon-apigateway-api-key-source property
](api-gateway-swagger-extensions-api-key-source.md)
+ [
# x-amazon-apigateway-auth object
](api-gateway-swagger-extensions-auth.md)
+ [
# x-amazon-apigateway-authorizer object
](api-gateway-swagger-extensions-authorizer.md)
+ [
# x-amazon-apigateway-authtype property
](api-gateway-swagger-extensions-authtype.md)
+ [
# x-amazon-apigateway-binary-media-types property
](api-gateway-swagger-extensions-binary-media-types.md)
+ [
# x-amazon-apigateway-documentation object
](api-gateway-swagger-extensions-documentation.md)
+ [
# x-amazon-apigateway-endpoint-access-mode
](openapi-extensions-endpoint-access-mode.md)
+ [
# x-amazon-apigateway-endpoint-configuration object
](api-gateway-swagger-extensions-endpoint-configuration.md)
+ [
# x-amazon-apigateway-gateway-responses object
](api-gateway-swagger-extensions-gateway-responses.md)
+ [
# x-amazon-apigateway-gateway-responses.gatewayResponse object
](api-gateway-swagger-extensions-gateway-responses.gatewayResponse.md)
+ [
# x-amazon-apigateway-gateway-responses.responseParameters object
](api-gateway-swagger-extensions-gateway-responses.responseParameters.md)
+ [
# x-amazon-apigateway-gateway-responses.responseTemplates object
](api-gateway-swagger-extensions-gateway-responses.responseTemplates.md)
+ [
# x-amazon-apigateway-importexport-version
](api-gateway-extensions-importexport-version.md)
+ [
# x-amazon-apigateway-integration object
](api-gateway-swagger-extensions-integration.md)
+ [
# x-amazon-apigateway-integrations object
](api-gateway-extensions-integrations.md)
+ [
# x-amazon-apigateway-integration.requestTemplates object
](api-gateway-swagger-extensions-integration-requestTemplates.md)
+ [
# x-amazon-apigateway-integration.requestParameters object
](api-gateway-swagger-extensions-integration-requestParameters.md)
+ [
# x-amazon-apigateway-integration.responses object
](api-gateway-swagger-extensions-integration-responses.md)
+ [
# x-amazon-apigateway-integration.response object
](api-gateway-swagger-extensions-integration-response.md)
+ [
# x-amazon-apigateway-integration.responseTemplates object
](api-gateway-swagger-extensions-integration-responseTemplates.md)
+ [
# x-amazon-apigateway-integration.responseParameters object
](api-gateway-swagger-extensions-integration-responseParameters.md)
+ [
# x-amazon-apigateway-integration.tlsConfig object
](api-gateway-extensions-integration-tls-config.md)
+ [
# x-amazon-apigateway-minimum-compression-size
](api-gateway-openapi-minimum-compression-size.md)
+ [
# x-amazon-apigateway-policy
](openapi-extensions-policy.md)
+ [
# x-amazon-apigateway-request-validator property
](api-gateway-swagger-extensions-request-validator.md)
+ [
# x-amazon-apigateway-request-validators object
](api-gateway-swagger-extensions-request-validators.md)
+ [
# x-amazon-apigateway-request-validators.requestValidator object
](api-gateway-swagger-extensions-request-validators.requestValidator.md)
+ [
# x-amazon-apigateway-security-policy
](openapi-extensions-security-policy.md)
+ [
# x-amazon-apigateway-tag-value property
](api-gateway-openapi-extensions-x-amazon-apigateway-tag-value.md)
# x-amazon-apigateway-any-method object
Specifies the [OpenAPI Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object) for the API Gateway catch-all `ANY` method in an [OpenAPI Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#path-item-object). This object can exist alongside other Operation objects and will catch any HTTP method that wasn't explicitly declared.
The following table lists the properties extended by API Gateway. For the other OpenAPI Operation properties, see the OpenAPI specification.
| Property name | Type | Description |
| --- | --- | --- |
| isDefaultRoute | Boolean | Specifies whether a route is the \$1default route. Supported only for HTTP APIs. To learn more, see [Create routes for HTTP APIs in API Gateway](http-api-develop-routes.md). |
| x-amazon-apigateway-integration | [x-amazon-apigateway-integration object](api-gateway-swagger-extensions-integration.md) | Specifies the integration of the method with the backend. This is an extended property of the [OpenAPI Operation](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object) object. The integration can be of type AWS, AWS\$1PROXY, HTTP, HTTP\$1PROXY, or MOCK. |
## x-amazon-apigateway-any-method examples
The following example integrates the `ANY` method on a proxy resource, `{proxy+}`, with a Lambda function, `TestSimpleProxy`.
```
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:TestSimpleProxy/invocations",
"httpMethod": "POST",
"type": "aws_proxy"
}
```
The following example creates a `$default` route for an HTTP API that integrates with a Lambda function, `HelloWorld`.
```
"/$default": {
"x-amazon-apigateway-any-method": {
"isDefaultRoute": true,
"x-amazon-apigateway-integration": {
"type": "AWS_PROXY",
"httpMethod": "POST",
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations",
"timeoutInMillis": 1000,
"connectionType": "INTERNET",
"payloadFormatVersion": 1.0
}
}
}
```
# x-amazon-apigateway-cors object
Specifies the cross-origin resource sharing (CORS) configuration for an HTTP API. The extension applies to the root-level OpenAPI structure. To learn more, see [Configure CORS for HTTP APIs in API Gateway](http-api-cors.md).
| Property name | Type | Description |
| --- | --- | --- |
| allowOrigins | Array | Specifies the allowed origins. |
| allowCredentials | Boolean | Specifies whether credentials are included in the CORS request. |
| exposeHeaders | Array | Specifies the headers that are exposed. |
| maxAge | Integer | Specifies the number of seconds that the browser should cache preflight request results. |
| allowMethods | Array | Specifies the allowed HTTP methods. |
| allowHeaders | Array | Specifies the allowed headers. |
## x-amazon-apigateway-cors example
The following is an example CORS configuration for an HTTP API.
```
"x-amazon-apigateway-cors": {
"allowOrigins": [
"https://www.example.com"
],
"allowCredentials": true,
"exposeHeaders": [
"x-apigateway-header",
"x-amz-date",
"content-type"
],
"maxAge": 3600,
"allowMethods": [
"GET",
"OPTIONS",
"POST"
],
"allowHeaders": [
"x-apigateway-header",
"x-amz-date",
"content-type"
]
}
```
# x-amazon-apigateway-api-key-source property
Specify the source to receive an API key to throttle API methods that require a key. This API-level property is a `String` type. For more information about configuring a method to require an API key, see [Configure a method to use API keys with an OpenAPI definition](api-key-usage-plan-oas.md).
Specify the source of the API key for requests. Valid values are:
+ `HEADER` for receiving the API key from the `X-API-Key` header of a request.
+ `AUTHORIZER` for receiving the API key from the `UsageIdentifierKey` from a Lambda authorizer (formerly known as a custom authorizer).
## x-amazon-apigateway-api-key-source example
The following example sets the `X-API-Key` header as the API key source.
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"title" : "Test1"
},
"schemes" : [ "https" ],
"basePath" : "/import",
"x-amazon-apigateway-api-key-source" : "HEADER",
.
.
.
}
```
------
#### [ OpenAPI 3.0.1 ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Test1"
},
"servers" : [ {
"url" : "/{basePath}",
"variables" : {
"basePath" : {
"default" : "import"
}
}
} ],
"x-amazon-apigateway-api-key-source" : "HEADER",
.
.
.
}
```
------
# x-amazon-apigateway-auth object
Defines an authorization type to be applied for authorization of method invocations in API Gateway.
| Property name | Type | Description |
| --- | --- | --- |
| type | string | Specifies the authorization type. Specify "NONE" for open access. Specify "AWS\$1IAM" to use IAM permissions. Values are case insensitive. |
## x-amazon-apigateway-auth example
The following example sets the authorization type for an API method.
------
#### [ OpenAPI 3.0.1 ]
```
{
"openapi": "3.0.1",
"info": {
"title": "openapi3",
"version": "1.0"
},
"paths": {
"/protected-by-iam": {
"get": {
"x-amazon-apigateway-auth": {
"type": "AWS_IAM"
}
}
}
}
}
```
------
# x-amazon-apigateway-authorizer object
Defines a Lambda authorizer, Amazon Cognito user pool, or JWT authorizer to be applied for authorization of method invocations in API Gateway. This extension applies to the security definition in [OpenAPI 2](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#security-definitions-object) and the security scheme in [OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md#security-scheme-object).
| Property name | Type | Description |
| --- | --- | --- |
| type | string | The type of the authorizer. This is a required property. For REST APIs, specify `token` for an authorizer with the caller identity embedded in an authorization token. Specify `request` for an authorizer with the caller identity contained in request parameters. Specify `cognito_user_pools` for an authorizer that uses an Amazon Cognito user pool to control access to your API. For HTTP APIs, specify `request` for a Lambda authorizer with the caller identity contained in request parameters. Specify `jwt` for a JWT authorizer. |
| authorizerUri | string | The Uniform Resource Identifier (URI) of the authorizer Lambda function. The syntax is as follows: "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:auth_function_name/invocations"
|
| authorizerCredentials | string | The credentials required for invoking the authorizer, if any, in the form of an ARN of an IAM execution role. For example, "arn:aws:iam::*account-id*:*IAM\$1role*". |
| authorizerPayloadFormatVersion | string | For HTTP APIs, specifies the format of the data that API Gateway sends to a Lambda authorizer, and how API Gateway interprets the response from Lambda. To learn more, see [Payload format version](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format). |
| enableSimpleResponses | Boolean | For HTTP APIs, specifies whether a `request` authorizer returns a Boolean value or an IAM policy. Supported only for authorizers with an `authorizerPayloadFormatVersion` of `2.0`. If enabled, the Lambda authorizer function returns a Boolean value. To learn more, see [Lambda function response for format 2.0](http-api-lambda-authorizer.md#http-api-lambda-authorizer.v2). |
| identitySource | string | A comma-separated list of mapping expressions of the request parameters as the identity source. Applicable for the authorizer of the `request` and `jwt` type only. |
| jwtConfiguration | Object | Specifies the issuer and audiences for a JWT authorizer. To learn more, see [JWTConfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration) in the API Gateway Version 2 API Reference. Supported only for HTTP APIs. |
| identityValidationExpression | string | A regular expression for validating the token as the incoming identity. For example, "^x-[a-z]\$1". Supported only for `TOKEN` authorizers for REST APIs. |
| authorizerResultTtlInSeconds | string | The number of seconds during which authorizer result is cached. |
| providerARNs | An array of string | A list of the Amazon Cognito user pool ARNs for the `COGNITO_USER_POOLS`. |
## x-amazon-apigateway-authorizer examples for REST APIs
The following OpenAPI security definitions example specifies a Lambda authorizer of the "token" type and named `test-authorizer`.
```
"securityDefinitions" : {
"test-authorizer" : {
"type" : "apiKey", // Required and the value must be "apiKey" for an API Gateway API.
"name" : "Authorization", // The name of the header containing the authorization token.
"in" : "header", // Required and the value must be "header" for an API Gateway API.
"x-amazon-apigateway-authtype" : "custom", // Specifies the authorization mechanism for the client.
"x-amazon-apigateway-authorizer" : { // An API Gateway Lambda authorizer definition
"type" : "token", // Required property and the value must "token"
"authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:function-name/invocations",
"authorizerCredentials" : "arn:aws:iam::account-id:role",
"identityValidationExpression" : "^x-[a-z]+",
"authorizerResultTtlInSeconds" : 60
}
}
}
```
The following OpenAPI operation object snippet sets the `GET /http` to use the preceding Lambda authorizer.
```
"/http" : {
"get" : {
"responses" : { },
"security" : [ {
"test-authorizer" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"type" : "http",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"httpMethod" : "GET",
"uri" : "http://api.example.com"
}
}
}
```
The following OpenAPI security definitions example specifies a Lambda authorizer of the "request" type, with a single header parameter (`auth`) as the identity source. The `securityDefinitions` is named `request_authorizer_single_header`.
```
"securityDefinitions": {
"request_authorizer_single_header" : {
"type" : "apiKey",
"name" : "auth", // The name of a single header or query parameter as the identity source.
"in" : "header", // The location of the single identity source request parameter. The valid value is "header" or "query"
"x-amazon-apigateway-authtype" : "custom",
"x-amazon-apigateway-authorizer" : {
"type" : "request",
"identitySource" : "method.request.header.auth", // Request parameter mapping expression of the identity source. In this example, it is the 'auth' header.
"authorizerCredentials" : "arn:aws:iam::123456789012:role/AWSepIntegTest-CS-LambdaRole",
"authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:APIGateway-Request-Authorizer:vtwo/invocations",
"authorizerResultTtlInSeconds" : 300
}
}
}
```
The following OpenAPI security definitions example specifies a Lambda authorizer of the "request" type, with one header (`HeaderAuth1`) and one query string parameter `QueryString1` as the identity sources.
```
"securityDefinitions": {
"request_authorizer_header_query" : {
"type" : "apiKey",
"name" : "Unused", // Must be "Unused" for multiple identity sources or non header or query type of request parameters.
"in" : "header", // Must be "header" for multiple identity sources or non header or query type of request parameters.
"x-amazon-apigateway-authtype" : "custom",
"x-amazon-apigateway-authorizer" : {
"type" : "request",
"identitySource" : "method.request.header.HeaderAuth1, method.request.querystring.QueryString1", // Request parameter mapping expressions of the identity sources.
"authorizerCredentials" : "arn:aws:iam::123456789012:role/AWSepIntegTest-CS-LambdaRole",
"authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:APIGateway-Request-Authorizer:vtwo/invocations",
"authorizerResultTtlInSeconds" : 300
}
}
}
```
The following OpenAPI security definitions example specifies an API Gateway Lambda authorizer of the "request" type, with a single stage variable (`stage`) as the identity source.
```
"securityDefinitions": {
"request_authorizer_single_stagevar" : {
"type" : "apiKey",
"name" : "Unused", // Must be "Unused", for multiple identity sources or non header or query type of request parameters.
"in" : "header", // Must be "header", for multiple identity sources or non header or query type of request parameters.
"x-amazon-apigateway-authtype" : "custom",
"x-amazon-apigateway-authorizer" : {
"type" : "request",
"identitySource" : "stageVariables.stage", // Request parameter mapping expression of the identity source. In this example, it is the stage variable.
"authorizerCredentials" : "arn:aws:iam::123456789012:role/AWSepIntegTest-CS-LambdaRole",
"authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:APIGateway-Request-Authorizer:vtwo/invocations",
"authorizerResultTtlInSeconds" : 300
}
}
}
```
The following OpenAPI security definition example specifies an Amazon Cognito user pool as an authorizer.
```
"securityDefinitions": {
"cognito-pool": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"x-amazon-apigateway-authtype": "cognito_user_pools",
"x-amazon-apigateway-authorizer": {
"type": "cognito_user_pools",
"providerARNs": [
"arn:aws:cognito-idp:us-east-1:123456789012:userpool/us-east-1_ABC123"
]
}
}
```
The following OpenAPI operation object snippet sets the `GET /http` to use the preceding Amazon Cognito user pool as an authorizer, with no custom scopes.
```
"/http" : {
"get" : {
"responses" : { },
"security" : [ {
"cognito-pool" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"type" : "http",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"httpMethod" : "GET",
"uri" : "http://api.example.com"
}
}
}
```
## x-amazon-apigateway-authorizer examples for HTTP APIs
The following OpenAPI 3.0 example creates a JWT authorizer for an HTTP API that uses Amazon Cognito as an identity provider, with the `Authorization` header as an identity source.
```
"securitySchemes": {
"jwt-authorizer-oauth": {
"type": "oauth2",
"x-amazon-apigateway-authorizer": {
"type": "jwt",
"jwtConfiguration": {
"issuer": "https://cognito-idp.region.amazonaws.com/userPoolId",
"audience": [
"audience1",
"audience2"
]
},
"identitySource": "$request.header.Authorization"
}
}
}
```
The following OpenAPI 3.0 example produces the same JWT authorizer as the previous example. However, this example uses the OpenAPI `openIdConnectUrl` property to automatically detect the issuer. The `openIdConnectUrl` must be fully formed.
```
"securitySchemes": {
"jwt-authorizer-autofind": {
"type": "openIdConnect",
"openIdConnectUrl": "https://cognito-idp.region.amazonaws.com/userPoolId/.well-known/openid-configuration",
"x-amazon-apigateway-authorizer": {
"type": "jwt",
"jwtConfiguration": {
"audience": [
"audience1",
"audience2"
]
},
"identitySource": "$request.header.Authorization"
}
}
}
```
The following example creates a Lambda authorizer for an HTTP API. This example authorizer uses the `Authorization` header as its identity source. The authorizer uses the `2.0` payload format version, and returns Boolean value, because `enableSimpleResponses` is set to `true`.
```
"securitySchemes" : {
"lambda-authorizer" : {
"type" : "apiKey",
"name" : "Authorization",
"in" : "header",
"x-amazon-apigateway-authorizer" : {
"type" : "request",
"identitySource" : "$request.header.Authorization",
"authorizerUri" : "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:function-name/invocations",
"authorizerPayloadFormatVersion" : "2.0",
"authorizerResultTtlInSeconds" : 300,
"enableSimpleResponses" : true
}
}
}
```
# x-amazon-apigateway-authtype property
For REST APIs, this extension can be used to define a custom type of a Lambda authorizer. In this case, the value is free-form. For example, an API may have multiple Lambda authorizers that use different internal schemes. You can use this extension to identify the internal scheme of a Lambda authorizer.
More commonly, in HTTP APIs and REST APIs, it can also be used as a way to define IAM authorization across several operations that share the same security scheme. In this case, the term `awsSigv4` is a reserved term, along with any term prefixed by `aws`.
This extension applies to the `apiKey` type security scheme in [OpenAPI 2](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#security-scheme-object) and [OpenAPI 3.](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md#security-scheme-object)
## x-amazon-apigateway-authtype example
The following OpenAPI 3 example defines IAM authorization across multiple resources in a REST API or HTTP API:
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "openapi3",
"version" : "1.0"
},
"paths" : {
"/operation1" : {
"get" : {
"responses" : {
"default" : {
"description" : "Default response"
}
},
"security" : [ {
"sigv4Reference" : [ ]
} ]
}
},
"/operation2" : {
"get" : {
"responses" : {
"default" : {
"description" : "Default response"
}
},
"security" : [ {
"sigv4Reference" : [ ]
} ]
}
}
},
"components" : {
"securitySchemes" : {
"sigv4Reference" : {
"type" : "apiKey",
"name" : "Authorization",
"in" : "header",
"x-amazon-apigateway-authtype": "awsSigv4"
}
}
}
}
```
The following OpenAPI 3 example defines a Lambda authorizer with a custom scheme for a REST API:
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "openapi3 for REST API",
"version" : "1.0"
},
"paths" : {
"/protected-by-lambda-authorizer" : {
"get" : {
"responses" : {
"200" : {
"description" : "Default response"
}
},
"security" : [ {
"myAuthorizer" : [ ]
} ]
}
}
},
"components" : {
"securitySchemes" : {
"myAuthorizer" : {
"type" : "apiKey",
"name" : "Authorization",
"in" : "header",
"x-amazon-apigateway-authorizer" : {
"identitySource" : "method.request.header.Authorization",
"authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:function-name/invocations",
"authorizerResultTtlInSeconds" : 300,
"type" : "request",
"enableSimpleResponses" : false
},
"x-amazon-apigateway-authtype": "Custom scheme with corporate claims"
}
}
},
"x-amazon-apigateway-importexport-version" : "1.0"
}
```
## See also
[authorizer.authType](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#apigw-Type-Authorizer-authType)
# x-amazon-apigateway-binary-media-types property
Specifies the list of binary media types to be supported by API Gateway, such as `application/octet-stream` and `image/jpeg`. This extension is a JSON array. It should be included as a top-level vendor extension to the OpenAPI document.
## x-amazon-apigateway-binary-media-types example
The following example shows the encoding lookup order of an API.
```
"x-amazon-apigateway-binary-media-types": [ "application/octet", "image/jpeg" ]
```
# x-amazon-apigateway-documentation object
Defines the documentation parts to be imported into API Gateway. This object is a JSON object containing an array of the `DocumentationPart` instances.
| Property name | Type | Description |
| --- | --- | --- |
| documentationParts | Array | An array of the exported or imported `DocumentationPart` instances. |
| version | String | The version identifier of the snapshot of the exported documentation parts. |
## x-amazon-apigateway-documentation example
The following example of the API Gateway extension to OpenAPI defines `DocumentationParts` instances to be imported to or exported from an API in API Gateway.
```
{ ...
"x-amazon-apigateway-documentation": {
"version": "1.0.3",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"info": {
"description": "API info description 4",
"version": "API info version 3"
}
}
},
{
… // Another DocumentationPart instance
}
]
}
}
```
# x-amazon-apigateway-endpoint-access-mode
Specifies a the endpoint access mode for a REST API or custom domain name. To learn more about endpoint access mode, see [Endpoint access mode](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode).
## `x-amazon-apigateway-endpoint-access-mode` example
The following example specifies the endpoint access mode to strict.
```
"x-amazon-apigateway-endpoint-access-mode": "STRICT"
```
# x-amazon-apigateway-endpoint-configuration object
Specifies details of the endpoint configuration for an API. This extension is an extended property of the [OpenAPI Operation](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#operation-object) object. This object should be present in [top-level vendor extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#specification-extensions) for Swagger 2.0. For OpenAPI 3.0, it should be present under the vendor extensions of the [Server object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#server-object).
| Property name | Type | Description |
| --- | --- | --- |
| disableExecuteApiEndpoint | Boolean | Specifies whether clients can invoke your API by using the default `execute-api` endpoint. By default, clients can invoke your API with the default `https://{api_id}.execute-api.{region}.amazonaws.com` endpoint. To require that clients use a custom domain name to invoke your API, specify `true`. |
| vpcEndpointIds | An array of String | A list of VpcEndpoint identifiers against which to create Route 53 alias records for a REST API. It is only supported for REST APIs the `PRIVATE` endpoint type. |
| ipAddressType | string | The IP address types that can invoke an HTTP API. Use `ipv4` to allow IPv4 address types to invoke an HTTP API. Use `dualstack` to allow IPv4 and IPv6 address types to invoke an HTTP API. It is only supported for HTTP APIs. |
## x-amazon-apigateway-endpoint-configuration examples
The following example associates specified VPC endpoints to the REST API.
```
"x-amazon-apigateway-endpoint-configuration": {
"vpcEndpointIds": ["vpce-0212a4ababd5b8c3e", "vpce-01d622316a7df47f9"]
}
```
The following example disables the default endpoint for an API.
```
"x-amazon-apigateway-endpoint-configuration": {
"disableExecuteApiEndpoint": true
}
```
The following example sets the IP address type to dualstack for an HTTP API.
```
"x-amazon-apigateway-endpoint-configuration": {
"ipAddressType": "dualstack"
}
```
# x-amazon-apigateway-gateway-responses object
Defines the gateway responses for an API as a string-to-[GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) map of key-value pairs. The extension applies to the root-level OpenAPI structure.
| Property name | Type | Description |
| --- | --- | --- |
| responseType | [x-amazon-apigateway-gateway-responses.gatewayResponse](api-gateway-swagger-extensions-gateway-responses.gatewayResponse.md) | A `GatewayResponse` for the specified *responseType*. |
## x-amazon-apigateway-gateway-responses example
The following API Gateway extension to OpenAPI example defines a [GatewayResponses](https://docs.aws.amazon.com/apigateway/latest/api/API_GetGatewayResponses.html) map that contains two [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) instances—one for the `DEFAULT_4XX` type and another for the `INVALID_API_KEY` type.
```
{
"x-amazon-apigateway-gateway-responses": {
"DEFAULT_4XX": {
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'domain.com'"
},
"responseTemplates": {
"application/json": "{\"message\": test 4xx b }"
}
},
"INVALID_API_KEY": {
"statusCode": "429",
"responseTemplates": {
"application/json": "{\"message\": test forbidden }"
}
}
}
}
```
# x-amazon-apigateway-gateway-responses.gatewayResponse object
Defines a gateway response of a given response type, including the status code, any applicable response parameters, or response templates.
| Property name | Type | Description |
| --- | --- | --- |
| responseParameters | [x-amazon-apigateway-gateway-responses.responseParameters](api-gateway-swagger-extensions-gateway-responses.responseParameters.md) | Specifies the [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) parameters, namely the header parameters. The parameter values can take any incoming [request parameter](rest-api-parameter-mapping.md) value or a static custom value. |
| responseTemplates | [x-amazon-apigateway-gateway-responses.responseTemplates](api-gateway-swagger-extensions-gateway-responses.responseTemplates.md) | Specifies the mapping templates of the gateway response. The templates are not processed by the VTL engine. |
| statusCode | string | An HTTP status code for the gateway response. |
## x-amazon-apigateway-gateway-responses.gatewayResponse example
The following example of the API Gateway extension to OpenAPI defines a [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) to customize the `INVALID_API_KEY` response to return the status code of `456`, the incoming request's `api-key` header value, and a `"Bad api-key"` message.
```
"INVALID_API_KEY": {
"statusCode": "456",
"responseParameters": {
"gatewayresponse.header.api-key": "method.request.header.api-key"
},
"responseTemplates": {
"application/json": "{\"message\": \"Bad api-key\" }"
}
}
```
# x-amazon-apigateway-gateway-responses.responseParameters object
Defines a string-to-string map of key-value pairs to generate gateway response parameters from the incoming request parameters or using literal strings. Supported only for REST APIs.
| Property name | Type | Description |
| --- | --- | --- |
| gatewayresponse.param-position.param-name | string | `param-position` can be `header`, `path`, or `querystring`. For more information, see [Parameter mapping for REST APIs in API Gateway](rest-api-parameter-mapping.md). |
## x-amazon-apigateway-gateway-responses.responseParameters example
The following OpenAPI extensions example shows a [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) response parameter mapping expression to enable CORS support for resources on the `*.example.domain` domains.
```
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": '*.example.domain',
"gatewayresponse.header.from-request-header" : method.request.header.Accept,
"gatewayresponse.header.from-request-path" : method.request.path.petId,
"gatewayresponse.header.from-request-query" : method.request.querystring.qname
}
```
# x-amazon-apigateway-gateway-responses.responseTemplates object
Defines [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) mapping templates, as a string-to-string map of key-value pairs, for a given gateway response. For each key-value pair, the key is the content type. For example, "application/json" and the value is a stringified mapping template for simple variable substitutions. A `GatewayResponse` mapping template isn't processed by the [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) engine.
| Property name | Type | Description |
| --- | --- | --- |
| content-type | string | A `GatewayResponse` body mapping template supporting only simple variable substitution to customize a gateway response body. |
## x-amazon-apigateway-gateway-responses.responseTemplates example
The following OpenAPI extensions example shows a [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) mapping template to customize an API Gateway–generated error response into an app-specific format.
```
"responseTemplates": {
"application/json": "{ \"message\": $context.error.messageString, \"type\":$context.error.responseType, \"statusCode\": '488' }"
}
```
The following OpenAPI extensions example shows a [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) mapping template to override an API Gateway–generated error response with a static error message.
```
"responseTemplates": {
"application/json": "{ \"message\": 'API-specific errors' }"
}
```
# x-amazon-apigateway-importexport-version
Specifies the version of the API Gateway import and export algorithm for HTTP APIs. Currently, the only supported value is `1.0`. To learn more, see [exportVersion](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-exports-specification.html#w125aab9c10b3b1b4) in the *API Gateway Version 2 API Reference*.
## x-amazon-apigateway-importexport-version example
The following example sets the import and export version to `1.0`.
```
{
"openapi": "3.0.1",
"x-amazon-apigateway-importexport-version": "1.0",
"info": { ...
```
# x-amazon-apigateway-integration object
Specifies details of the backend integration used for this method. This extension is an extended property of the [OpenAPI Operation](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object) object. The result is an [API Gateway integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) object.
| Property name | Type | Description |
| --- | --- | --- |
| cacheKeyParameters | An array of string | A list of request parameters whose values are to be cached. |
| cacheNamespace | string | An API-specific tag group of related cached parameters. |
| connectionId | string | The ID of a [VpcLink](https://docs.aws.amazon.com/apigateway/latest/api/API_VpcLink.html) for the private integration. |
| connectionType | string | The integration connection type. The valid value is "VPC\$1LINK" for private integration or "INTERNET", otherwise. |
| credentials | string | For AWS IAM role-based credentials, specify the ARN of an appropriate IAM role. If unspecified, credentials default to resource-based permissions that must be added manually to allow the API to access the resource. For more information, see [Granting Permissions Using a Resource Policy](https://docs.aws.amazon.com/lambda/latest/dg/lambda-permissions.html#intro-permission-model-access-policy). Note: When using IAM credentials, make sure that [AWS STS Regional endpoints](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html) are enabled for the Region where this API is deployed for best performance. |
| contentHandling | string | Request payload encoding conversion types. Valid values are 1) CONVERT\$1TO\$1TEXT, for converting a binary payload into a base64-encoded string or converting a text payload into a utf-8-encoded string or passing through the text payload natively without modification, and 2) CONVERT\$1TO\$1BINARY, for converting a text payload into a base64-decoded blob or passing through a binary payload natively without modification. |
| httpMethod | string | The HTTP method used in the integration request. For Lambda function invocations, the value must be POST. |
| integrationSubtype | string | Specifies the integration subtype for an AWS service integration. Supported only for HTTP APIs. For supported integration subtypes, see [Integration subtype reference](http-api-develop-integrations-aws-services-reference.md). |
| integrationTarget | string | The ALB or NLB listener to send the request to. Supported only for private integrations that use VPC links V2. For more information, see [Set up VPC links V2 in API Gateway](apigateway-vpc-links-v2.md). |
| passthroughBehavior | string | Specifies how a request payload of unmapped content type is passed through the integration request without modification. Supported values are when\$1no\$1templates, when\$1no\$1match, and never. For more information, see [Integration.passthroughBehavior](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#passthroughBehavior). |
| payloadFormatVersion | string | Specifies the format of the payload sent to an integration. Required for HTTP APIs. For HTTP APIs, supported values for Lambda proxy integrations are 1.0 and 2.0. For all other integrations, 1.0 is the only supported value. To learn more, see [Create AWS Lambda proxy integrations for HTTP APIs in API Gateway](http-api-develop-integrations-lambda.md) and [Integration subtype reference](http-api-develop-integrations-aws-services-reference.md). |
| requestParameters | [x-amazon-apigateway-integration.requestParameters object](api-gateway-swagger-extensions-integration-requestParameters.md) | For REST APIs, specifies mappings from method request parameters to integration request parameters. Supported request parameters are `querystring`, `path`, `header`, and `body`. For HTTP APIs, request parameters are a key-value map specifying parameters that are passed to `AWS_PROXY` integrations with a specified `integrationSubtype`. You can provide static values, or map request data, stage variables, or context variables that are evaluated at runtime. To learn more, see [Create AWS service integrations for HTTP APIs in API Gateway](http-api-develop-integrations-aws-services.md). |
| requestTemplates | [x-amazon-apigateway-integration.requestTemplates object](api-gateway-swagger-extensions-integration-requestTemplates.md) | Mapping templates for a request payload of specified MIME types. |
| responses | [x-amazon-apigateway-integration.responses object](api-gateway-swagger-extensions-integration-responses.md) | Defines the method's responses and specifies desired parameter mappings or payload mappings from integration responses to method responses. |
| responseTransferMode | string | The response transfer mode of the integration. Use BUFFERED to have API Gateway wait to receive the complete response before beginning transmission. Use STREAM to have API Gateway send partial responses back to the client as they become available. To learn more, see [Stream the integration response for your proxy integrations in API Gateway](response-transfer-mode.md). |
| timeoutInMillis | integer | Integration timeouts between 50 ms and 29,000 ms. |
| type | string | The type of integration with the specified backend. Valid values are: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration.html) For more information about the integration types, see [integration:type](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type). |
| tlsConfig | [x-amazon-apigateway-integration.tlsConfig object](api-gateway-extensions-integration-tls-config.md) | Specifies the TLS configuration for an integration. |
| uri | string | The endpoint URI of the backend. For integrations of the aws type, this is an ARN value. For the HTTP integration, this is the URL of the HTTP endpoint including the https or http scheme. |
## x-amazon-apigateway-integration examples
For HTTP APIs, you can define integrations in the components section of your OpenAPI definition. To learn more, see [x-amazon-apigateway-integrations object](api-gateway-extensions-integrations.md).
```
"x-amazon-apigateway-integration": {
"$ref": "#/components/x-amazon-apigateway-integrations/integration1"
}
```
The following example creates an integration with a Lambda function. For demonstration purposes, the sample mapping templates shown in `requestTemplates` and `responseTemplates` of the examples below are assumed to apply to the following JSON-formatted payload: `{ "name":"value_1", "key":"value_2", "redirect": {"url" :"..."} }` to generate a JSON output of `{ "stage":"value_1", "user-id":"value_2" }` or an XML output of `value_1`.
```
"x-amazon-apigateway-integration" : {
"type" : "aws",
"uri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:012345678901:function:HelloWorld/invocations",
"httpMethod" : "POST",
"credentials" : "arn:aws:iam::012345678901:role/apigateway-invoke-lambda-exec-role",
"requestTemplates" : {
"application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
"application/xml" : "#set ($root=$input.path('$')) $root.name "
},
"requestParameters" : {
"integration.request.path.stage" : "method.request.querystring.version",
"integration.request.querystring.provider" : "method.request.querystring.vendor"
},
"cacheNamespace" : "cache namespace",
"cacheKeyParameters" : [],
"responses" : {
"2\\d{2}" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.requestId" : "integration.response.header.cid"
},
"responseTemplates" : {
"application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
"application/xml" : "#set ($root=$input.path('$')) $root.name "
}
},
"302" : {
"statusCode" : "302",
"responseParameters" : {
"method.response.header.Location" : "integration.response.body.redirect.url"
}
},
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
}
}
}
}
```
Note that double quotes (") for the JSON string in the mapping templates must be string-escaped (\$1").
# x-amazon-apigateway-integrations object
Defines a collection of integrations. You can define integrations in the components section of your OpenAPI definition, and reuse the integrations for multiple routes. Supported only for HTTP APIs.
| Property name | Type | Description |
| --- | --- | --- |
| integration | [x-amazon-apigateway-integration object](api-gateway-swagger-extensions-integration.md) | A collection of integration objects. |
## x-amazon-apigateway-integrations example
The following example creates an HTTP API that defines two integrations, and references the integrations by using `$ref": "#/components/x-amazon-apigateway-integrations/integration-name`.
```
{
"openapi": "3.0.1",
"info":
{
"title": "Integrations",
"description": "An API that reuses integrations",
"version": "1.0"
},
"servers": [
{
"url": "https://example.com/{basePath}",
"description": "The production API server",
"variables":
{
"basePath":
{
"default": "example/path"
}
}
}],
"paths":
{
"/":
{
"get":
{
"x-amazon-apigateway-integration":
{
"$ref": "#/components/x-amazon-apigateway-integrations/integration1"
}
}
},
"/pets":
{
"get":
{
"x-amazon-apigateway-integration":
{
"$ref": "#/components/x-amazon-apigateway-integrations/integration1"
}
}
},
"/checkout":
{
"get":
{
"x-amazon-apigateway-integration":
{
"$ref": "#/components/x-amazon-apigateway-integrations/integration2"
}
}
}
},
"components": {
"x-amazon-apigateway-integrations":
{
"integration1":
{
"type": "aws_proxy",
"httpMethod": "POST",
"uri": "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations",
"passthroughBehavior": "when_no_templates",
"payloadFormatVersion": "1.0"
},
"integration2":
{
"type": "aws_proxy",
"httpMethod": "POST",
"uri": "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:example-function/invocations",
"passthroughBehavior": "when_no_templates",
"payloadFormatVersion" : "1.0"
}
}
}
}
```
# x-amazon-apigateway-integration.requestTemplates object
Specifies mapping templates for a request payload of the specified MIME types.
| Property name | Type | Description |
| --- | --- | --- |
| MIME type | string | An example of the MIME type is `application/json`. For information about creating a mapping template, see [Mapping template transformations for REST APIs in API Gateway](models-mappings.md). |
## x-amazon-apigateway-integration.requestTemplates example
The following example sets mapping templates for a request payload of the `application/json` and `application/xml` MIME types.
```
"requestTemplates" : {
"application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
"application/xml" : "#set ($root=$input.path('$')) $root.name "
}
```
# x-amazon-apigateway-integration.requestParameters object
For REST APIs, specifies mappings from named method request parameters to integration request parameters. The method request parameters must be defined before being referenced.
For HTTP APIs, specifies parameters that are passed to `AWS_PROXY` integrations with a specified `integrationSubtype`.
| Property name | Type | Description |
| --- | --- | --- |
| integration.request.. | string | For REST APIs, the value is typically a predefined method request parameter of the `method.request..` format, where `` can be `querystring`, `path`, `header`, or `body`. However, `$context.VARIABLE_NAME`, `$stageVariables.VARIABLE_NAME`, and `STATIC_VALUE` are also valid. For the `body` parameter, the `` is a JSON path expression without the `$.` prefix. |
| parameter | string | For HTTP APIs, request parameters are a key-value map specifying parameters that are passed to `AWS_PROXY` integrations with a specified `integrationSubtype`. You can provide static values, or map request data, stage variables, or context variables that are evaluated at runtime. To learn more, see [Create AWS service integrations for HTTP APIs in API Gateway](http-api-develop-integrations-aws-services.md). |
## `x-amazon-apigateway-integration.requestParameters` example
The following request parameter mappings example translates a method request's query (`version`), header (`x-user-id`), and path (`service`) parameters to the integration request's query (`stage`), header (`x-userid`), and path parameters (`op`), respectively.
**Note**
If you're creating resources through OpenAPI or CloudFormation, static values should be enclosed in single quotes.
To add this value from the console, enter `application/json` in the box, without quotation marks.
```
"requestParameters" : {
"integration.request.querystring.stage" : "method.request.querystring.version",
"integration.request.header.x-userid" : "method.request.header.x-user-id",
"integration.request.path.op" : "method.request.path.service"
},
```
# x-amazon-apigateway-integration.responses object
Defines the method's responses and specifies parameter mappings or payload mappings from integration responses to method responses.
| Property name | Type | Description |
| --- | --- | --- |
| Response status pattern | [x-amazon-apigateway-integration.response object](api-gateway-swagger-extensions-integration-response.md) | Either a regular expression used to match the integration response to the method response, or `default` to catch any response that you haven't configured. For HTTP integrations, the regex applies to the integration response status code. For Lambda invocations, the regex applies to the `errorMessage` field of the error information object returned by AWS Lambda as a failure response body when the Lambda function execution throws an exception. The *Response status pattern* property name refers to a response status code or regular expression describing a group of response status codes. It does not correspond to any identifier of an [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) resource in the API Gateway REST API. |
## `x-amazon-apigateway-integration.responses` example
The following example shows a list of responses from `2xx` and `302` responses. For the `2xx` response, the method response is mapped from the integration response's payload of the `application/json` or `application/xml` MIME type. This response uses the supplied mapping templates. For the `302` response, the method response returns a `Location` header whose value is derived from the `redirect.url` property on the integration response's payload.
```
"responses" : {
"2\\d{2}" : {
"statusCode" : "200",
"responseTemplates" : {
"application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
"application/xml" : "#set ($root=$input.path('$')) $root.name "
}
},
"302" : {
"statusCode" : "302",
"responseParameters" : {
"method.response.header.Location": "integration.response.body.redirect.url"
}
}
}
```
# x-amazon-apigateway-integration.response object
Defines a response and specifies parameter mappings or payload mappings from the integration response to the method response.
| Property name | Type | Description |
| --- | --- | --- |
| statusCode | string | HTTP status code for the method response; for example, `"200"`. This must correspond to a matching response in the [OpenAPI Operation](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object) `responses` field. |
| responseTemplates | [x-amazon-apigateway-integration.responseTemplates object](api-gateway-swagger-extensions-integration-responseTemplates.md) | Specifies MIME type-specific mapping templates for the response’s payload. |
| responseParameters | [x-amazon-apigateway-integration.responseParameters object](api-gateway-swagger-extensions-integration-responseParameters.md) | Specifies parameter mappings for the response. Only the `header` and `body` parameters of the integration response can be mapped to the `header` parameters of the method. |
| contentHandling | string | Response payload encoding conversion types. Valid values are 1) CONVERT\$1TO\$1TEXT, for converting a binary payload into a base64-encoded string or converting a text payload into a utf-8-encoded string or passing through the text payload natively without modification, and 2) CONVERT\$1TO\$1BINARY, for converting a text payload into a base64-decoded blob or passing through a binary payload natively without modification. |
## `x-amazon-apigateway-integration.response` example
The following example defines a `302` response for the method that derives a payload of the `application/json` or `application/xml` MIME type from the backend. The response uses the supplied mapping templates and returns the redirect URL from the integration response in the method's `Location` header.
```
{
"statusCode" : "302",
"responseTemplates" : {
"application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
"application/xml" : "#set ($root=$input.path('$')) $root.name "
},
"responseParameters" : {
"method.response.header.Location": "integration.response.body.redirect.url"
}
}
```
# x-amazon-apigateway-integration.responseTemplates object
Specifies mapping templates for a response payload of the specified MIME types.
| Property name | Type | Description |
| --- | --- | --- |
| MIME type | string | Specifies a mapping template to transform the integration response body to the method response body for a given MIME type. For information about creating a mapping template, see [Mapping template transformations for REST APIs in API Gateway](models-mappings.md). An example of the *MIME type* is `application/json`. |
## x-amazon-apigateway-integration.responseTemplate example
The following example sets mapping templates for a request payload of the `application/json` and `application/xml` MIME types.
```
"responseTemplates" : {
"application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
"application/xml" : "#set ($root=$input.path('$')) $root.name "
}
```
# x-amazon-apigateway-integration.responseParameters object
Specifies mappings from integration method response parameters to method response parameters. You can map `header`, `body`, or static values to the `header` type of the method response. Supported only for REST APIs.
| Property name | Type | Description |
| --- | --- | --- |
| method.response.header. | string | The named parameter value can be derived from the `header` and `body` types of the integration response parameters. |
## `x-amazon-apigateway-integration.responseParameters` example
The following example maps `body` and `header` parameters of the integration response to two `header` parameters of the method response.
```
"responseParameters" : {
"method.response.header.Location" : "integration.response.body.redirect.url",
"method.response.header.x-user-id" : "integration.response.header.x-userid"
}
```
# x-amazon-apigateway-integration.tlsConfig object
Specifies the TLS configuration for an integration.
| Property name | Type | Description |
| --- | --- | --- |
| insecureSkipVerification | Boolean | Supported only for REST APIs. Specifies whether or not API Gateway skips verification that the certificate for an integration endpoint is issued by a [supported certificate authority](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-supported-certificate-authorities-for-http-endpoints.html). This isn’t recommended, but it enables you to use certificates that are signed by private certificate authorities, or certificates that are self-signed. If enabled, API Gateway still performs basic certificate validation, which includes checking the certificate's expiration date, hostname, and presence of a root certificate authority. The root certificate belonging to the private authority must satisfy the following constraints: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-extensions-integration-tls-config.html) Supported only for `HTTP` and `HTTP_PROXY` integrations. Enabling `insecureSkipVerification` isn't recommended, especially for integrations with public HTTPS endpoints. If you enable `insecureSkipVerification`, you increase the risk of man-in-the-middle attacks. |
| serverNameToVerify | string | Supported only for HTTP API private integrations. If you specify a server name, API Gateway uses it to verify the hostname on the integration's certificate. The server name is also included in the TLS handshake to support Server Name Indication (SNI) or virtual hosting. |
## x-amazon-apigateway-integration.tlsConfig examples
The following OpenAPI 3.0 example enables `insecureSkipVerification` for a REST API HTTP proxy integration.
```
"x-amazon-apigateway-integration": {
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses": {
default": {
"statusCode": "200"
}
},
"passthroughBehavior": "when_no_match",
"httpMethod": "ANY",
"tlsConfig" : {
"insecureSkipVerification" : true
}
"type": "http_proxy",
}
```
The following OpenAPI 3.0 example specifies a `serverNameToVerify` for an HTTP API private integration.
```
"x-amazon-apigateway-integration" : {
"payloadFormatVersion" : "1.0",
"connectionId" : "abc123",
"type" : "http_proxy",
"httpMethod" : "ANY",
"uri" : "arn:aws:elasticloadbalancing:us-west-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/0467ef3c8400ae65",
"connectionType" : "VPC_LINK",
"tlsConfig" : {
"serverNameToVerify" : "example.com"
}
}
```
# x-amazon-apigateway-minimum-compression-size
Specifies the minimum compression size for a REST API. To enable compression, specify an integer between 0 and 10485760. To learn more, see [Payload compression for REST APIs in API Gateway](api-gateway-gzip-compression-decompression.md).
## x-amazon-apigateway-minimum-compression-size example
The following example specifies a minimum compression size of `5242880` bytes for a REST API.
```
"x-amazon-apigateway-minimum-compression-size": 5242880
```
# x-amazon-apigateway-policy
Specifies a resource policy for a REST API. To learn more about resource policies, see [Control access to a REST API with API Gateway resource policies](apigateway-resource-policies.md). For resource policy examples, see [API Gateway resource policy examples](apigateway-resource-policies-examples.md).
## `x-amazon-apigateway-policy` example
The following example specifies a resource policy for a REST API. The resource policy denies (blocks) incoming traffic to an API from a specified source IP address block. On import, `"execute-api:/*"` is converted to `arn:aws:execute-api:region:account-id:api-id/*`, using the current Region, your AWS account ID, and the current REST API ID.
```
"x-amazon-apigateway-policy": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"IpAddress": {
"aws:SourceIp": "192.0.2.0/24"
}
}
}
]
}
```
# x-amazon-apigateway-request-validator property
Specifies a request validator, by referencing a `request_validator_name` of the [x-amazon-apigateway-request-validators object](api-gateway-swagger-extensions-request-validators.md) map, to enable request validation on the containing API or a method. The value of this extension is a JSON string.
This extension can be specified at the API level or at the method level. The API-level validator applies to all of the methods unless it is overridden by the method-level validator.
## `x-amazon-apigateway-request-validator` example
The following example applies the `basic` request validator at the API level while applying the `parameter-only` request validator on the `POST /validation` request.
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"x-amazon-apigateway-request-validators" : {
"basic" : {
"validateRequestBody" : true,
"validateRequestParameters" : true
},
"params-only" : {
"validateRequestBody" : false,
"validateRequestParameters" : true
}
},
"x-amazon-apigateway-request-validator" : "basic",
"paths": {
"/validation": {
"post": {
"x-amazon-apigateway-request-validator" : "params-only",
...
}
}
```
------
# x-amazon-apigateway-request-validators object
Defines the supported request validators for the containing API as a map between a validator name and the associated request validation rules. This extension applies to a REST API.
| Property name | Type | Description |
| --- | --- | --- |
| `request_validator_name` | [x-amazon-apigateway-request-validators.requestValidator object](api-gateway-swagger-extensions-request-validators.requestValidator.md) | Specifies the validation rules consisting of the named validator. For example: "basic" : {
"validateRequestBody" : true,
"validateRequestParameters" : true
},
To apply this validator to a specific method, reference the validator name (`basic`) as the value of the [x-amazon-apigateway-request-validator property](api-gateway-swagger-extensions-request-validator.md) property. |
## `x-amazon-apigateway-request-validators` example
The following example shows a set of request validators for an API as a map between a validator name and the associated request validation rules.
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
...
"x-amazon-apigateway-request-validators" : {
"basic" : {
"validateRequestBody" : true,
"validateRequestParameters" : true
},
"params-only" : {
"validateRequestBody" : false,
"validateRequestParameters" : true
}
},
...
}
```
------
# x-amazon-apigateway-request-validators.requestValidator object
Specifies the validation rules of a request validator as part of the [x-amazon-apigateway-request-validators object](api-gateway-swagger-extensions-request-validators.md) map definition.
| Property name | Type | Description |
| --- | --- | --- |
| `validateRequestBody` | Boolean | Specifies whether to validate the request body (`true`) or not (`false`). |
| `validateRequestParameters` | Boolean | Specifies whether to validate the required request parameters (`true`) or not (`false`). |
## `x-amazon-apigateway-request-validators.requestValidator` example
The following example shows a parameter-only request validator:
```
"params-only": {
"validateRequestBody" : false,
"validateRequestParameters" : true
}
```
# x-amazon-apigateway-security-policy
Specifies a security policy for a REST API. If you create a security policy that starts with `"SecurityPolicy_"`, you must also set the [endpoint access mode](openapi-extensions-endpoint-access-mode.md). To learn more about security policies, see [Security policies for REST APIs in API Gateway](apigateway-security-policies.md).
## `x-amazon-apigateway-security-policy` example
The following example specifies `SecurityPolicy_TLS13_1_3_2025_0` for a REST API.
```
"x-amazon-apigateway-security-policy": "SecurityPolicy_TLS13_1_3_2025_09"
```
# x-amazon-apigateway-tag-value property
Specifies the value of an [AWS tag](https://docs.aws.amazon.com/tag-editor/latest/userguide/tagging.html) for an HTTP API. You can use the `x-amazon-apigateway-tag-value` property as part of the root-level [OpenAPI tag object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#tag-object) to specify AWS tags for an HTTP API. If you specify a tag name without the `x-amazon-apigateway-tag-value` property, API Gateway creates a tag with an empty string for a value.
To learn more about tagging, see [Tagging your API Gateway resources](apigateway-tagging.md).
| Property name | Type | Description |
| --- | --- | --- |
| `name` | String | Specifies the tag key. |
| `x-amazon-apigateway-tag-value` | String | Specifies the tag value. |
## `x-amazon-apigateway-tag-value` example
The following example specifies two tags for an HTTP API:
+ "Owner": "Admin"
+ "Prod": ""
```
"tags": [
{
"name": "Owner",
"x-amazon-apigateway-tag-value": "Admin"
},
{
"name": "Prod"
}
]
```