Amazon API Gateway traits¶
Smithy can integrate with Amazon API Gateway using traits, authentication schemes, and OpenAPI specifications.
Method and response handling¶
aws.apigateway#gatewayResponses trait¶
- Summary
Defines custom gateway responses for an API Gateway REST API. Gateway responses customize error responses for authentication failures, integration errors, and other API Gateway-generated errors.
- Trait selector
service- Value type
mapof response typestringtoGatewayResponsestructure- See also
x-amazon-apigateway-gateway-responses for the related OpenAPI extension
Gateway response types for the list of valid response type keys
The GatewayResponse structure supports the following members:
Property |
Type |
Description |
|---|---|---|
statusCode |
|
The HTTP status code for the gateway response. |
responseParameters |
|
Response parameters for the gateway response. Keys use the format
|
responseTemplates |
|
Response templates keyed by media type. |
Note
Response type keys (DEFAULT_4XX, DEFAULT_5XX,
INVALID_API_KEY, etc.) are validated by API Gateway at import
time, not by Smithy. When both @gatewayResponses and
@cors are applied to a service, the CORS mapper merges
its headers into gateway responses but does not overwrite
customer-defined response parameters. Customer-defined values
always take precedence.
The following example defines custom gateway responses for 4xx and 5xx errors:
$version: "2"
namespace smithy.example
use aws.apigateway#gatewayResponses
@gatewayResponses(
"DEFAULT_4XX": {
statusCode: "400"
responseParameters: {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
}
responseTemplates: {
"application/json": "{\"message\": \"bad request\"}"
}
}
"DEFAULT_5XX": {
statusCode: "500"
responseTemplates: {
"application/json": "{\"message\": \"Internal server error\"}"
}
}
)
service Weather {
version: "2018-03-17"
}
Validation¶
Smithy emits a DANGER validation event when both
@gatewayResponses and cors trait are applied to the same
service. This is informational, customer-defined response
parameters in @gatewayResponses take precedence over
CORS-generated headers. Review the merged output to confirm the
effective headers match your intent.
aws.apigateway#minimumCompressionSize trait¶
- Summary
Defines the minimum payload size in bytes at which compression is applied on an API Gateway REST API.
- Trait selector
service- Value type
integervalue between 0 and 10485760 (10MB).- See also
Payload compression for REST APIs for more information
x-amazon-apigateway-minimum-compression-size for how this relates to OpenAPI
The following example sets the minimum compression size to 10240 bytes:
$version: "2"
namespace smithy.example
use aws.apigateway#minimumCompressionSize
@minimumCompressionSize(10240)
service Weather {
version: "2018-03-17"
}
aws.apigateway#requestValidator trait¶
- Summary
Opts-in to Amazon API Gateway request validation for a service or operation.
- Trait selector
:test(service, operation)- Value type
stringvalue set to one of the following:Value
Description
fullThe parameters and body of a request are validated.
params-onlyOnly the parameters of a request are validated.
body-onlyOnly the body of a request is validated.
- See also
Enable Request Validation in API Gateway for more information
Request validators for information on how this converts to OpenAPI
x-amazon-apigateway-request-validator for more on how this converts to OpenAPI
x-amazon-apigateway-request-validators for more on how this converts to OpenAPI
The following example enables request validation on a service:
$version: "2"
namespace smithy.example
use aws.apigateway#requestValidator
@requestValidator("full")
service Weather {
version: "2018-03-17"
}
Note
This trait should be considered internal-only and not exposed to your customers.
Warning
API Gateway request validation uses JSON Schema to validate requests against models and may not meet all the validation needs of your application.
Integrations¶
aws.apigateway#integration trait¶
- Summary
Defines an API Gateway integration that integrates with an actual backend.
- Trait selector
:test(service, resource, operation)- Value type
structure- See also
Integrations for information on how this converts to OpenAPI
API Gateway Integration for in-depth API documentation
x-amazon-apigateway-integration for details on how this looks to OpenAPI
The aws.apigateway#integration trait is a structure that supports the
following members:
Property |
Type |
Description |
|---|---|---|
type |
|
Required. The type of integration with the specified backend. Valid values are:
|
uri |
|
Required. The endpoint URI of the backend. For integrations of
the |
httpMethod |
|
Required. Specifies the integration's HTTP method type
(for example, |
credentials |
|
Specifies the credentials required for the integration, if any. For AWS IAM role-based credentials, specify the ARN of an appropriate IAM role. If unspecified, credentials will 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. |
passThroughBehavior |
|
Specifies how a request payload of unmapped content type is passed
through the integration request without modification. Supported
values are |
contentHandling |
Request payload content handling. |
|
timeoutInMillis |
|
Integration timeouts between 50 ms and 29,000 ms. |
connectionId |
|
The ID of a VpcLink for the private integration. |
connectionType |
|
The type of the network connection to the integration endpoint.
The valid value is |
cacheNamespace |
|
An API-specific tag group of related cached parameters. |
payloadFormatVersion |
|
Specifies the format of the payload sent to an integration. This
property is required for HTTP APIs. Supported values for Lambda proxy
integrations are |
cacheKeyParameters |
|
A list of request parameter names whose values are to be cached. |
requestParameters |
|
Specifies mappings from method request parameters to integration request parameters. Supported request parameters are querystring, path, header, and body. |
requestTemplates |
|
Mapping templates for a request payload of specified media types. |
responses |
|
Defines the method's responses and specifies desired parameter mappings or payload mappings from integration responses to method responses. |
The following example defines an integration that is applied to every operation within the service.
{
"version": "2.0",
"shapes": {
"smithy.example#Weather": {
"type": "service",
"version": "2018-03-17",
"traits": {
"aws.protocols#restJson1": {},
"aws.auth#sigv4": {
"name": "weather"
},
"aws.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('$')) <stage>$root.name</stage> "
},
"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('$')) <stage>$root.name</stage> "
}
},
"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
This trait should be considered internal-only and not exposed to your customers.
aws.apigateway#mockIntegration trait¶
- Summary
Defines an API Gateway integration that returns a mock response.
- Trait selector
:test(service, resource, operation)- Value type
structure
The aws.apigateway#mockIntegration trait is a structure that supports the
following members:
Property |
Type |
Description |
|---|---|---|
passThroughBehavior |
|
Specifies how a request payload of unmapped content type is passed
through the integration request without modification. Supported
values are |
requestParameters |
|
Specifies mappings from method request parameters to integration request parameters. Supported request parameters are querystring, path, header, and body. |
requestTemplates |
|
Mapping templates for a request payload of specified media types. |
responses |
|
Defines the method's responses and specifies desired parameter mappings or payload mappings from integration responses to method responses. |
The following example defines an operation that uses a mock integration.
{
"smithy": "2.0",
"shapes": {
"smithy.example#MyOperation": {
"type": "operation",
"traits": {
"smithy.api#http": {
"method": "POST",
"uri": "/2"
},
"aws.apigateway#mockIntegration": {
"requestTemplates": {
"application/json": "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
"application/xml": "#set ($root=$input.path('$')) <stage>$root.name</stage> "
},
"requestParameters": {
"integration.request.path.stage": "method.request.querystring.version",
"integration.request.querystring.provider": "method.request.querystring.vendor"
},
"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('$')) <stage>$root.name</stage> "
}
},
"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
This trait should be considered internal-only and not exposed to your customers.
API endpoint and access control¶
aws.apigateway#apiTlsPolicy trait¶
- Summary
Defines the TLS security policy and endpoint access mode for an API Gateway REST API. The security policy specifies the TLS version and cipher suite, and the endpoint access mode controls how the API endpoint can be accessed.
- Trait selector
service- Value type
structure
The aws.apigateway#apiTlsPolicy trait is a structure that supports the
following members:
Property |
Type |
Description |
|---|---|---|
securityPolicy |
|
Required. The TLS version and cipher suite for the API (for
example, |
endpointAccessMode |
|
The endpoint access mode for the API. Valid values are |
- See also
Security policies for REST APIs for more information
x-amazon-apigateway-security-policy for how the security policy relates to OpenAPI
x-amazon-apigateway-endpoint-access-mode for how the endpoint access mode relates to OpenAPI
The following example sets the TLS policy to TLS_1_2 with a STRICT
endpoint access mode:
$version: "2"
namespace smithy.example
use aws.apigateway#apiTlsPolicy
@apiTlsPolicy(
securityPolicy: "TLS_1_2"
endpointAccessMode: "STRICT"
)
service Weather {
version: "2018-03-17"
}
Note
This trait should be considered internal-only and not exposed to your customers.
aws.apigateway#endpointConfiguration trait¶
- Summary
Defines the endpoint configuration for an API Gateway REST API, including the endpoint type, Virtual Private Cloud (VPC) endpoint IDs, and whether the default
execute-apiendpoint is disabled.- Trait selector
service- Value type
structure- See also
API endpoint types for REST APIs for more information on endpoint types
IP address types for REST APIs for more information on the
ipAddressTypepropertyx-amazon-apigateway-endpoint-configuration for the related OpenAPI extension
The aws.apigateway#endpointConfiguration trait is a structure that
supports the following members:
Property |
Type |
Description |
|---|---|---|
types |
|
Required. The endpoint types for the API. Valid values are
|
vpcEndpointIds |
|
A list of VPC endpoint IDs for |
disableExecuteApiEndpoint |
|
Whether clients can invoke the API using the default
|
ipAddressType |
|
The IP address type that can invoke the API. For the |
The following example configures a private API with a VPC endpoint and disables the default endpoint:
$version: "2"
namespace smithy.example
use aws.apigateway#endpointConfiguration
@endpointConfiguration(
types: ["PRIVATE"]
vpcEndpointIds: ["vpce-0212a4ababd5b8c3e"]
disableExecuteApiEndpoint: true
ipAddressType: "dualstack"
)
service Weather {
version: "2018-03-17"
}
Validation¶
Smithy emits an ERROR validation event when the PRIVATE endpoint
type is used with an ipAddressType other than dualstack. API Gateway
requires dualstack for private endpoints.
Note
This trait should be considered internal-only and not exposed to your customers.
aws.apigateway#resourcePolicy trait¶
- Summary
Defines a resource policy for an API Gateway REST API. A resource policy is a JSON policy document attached to an API that controls whether a specified principal (typically an IAM role or group) can invoke the API.
- Trait selector
service- Value type
document- See also
Resource policies for REST APIs for more information
x-amazon-apigateway-policy for how this relates to OpenAPI
Note
Smithy does not validate the contents of the resource policy document. The policy is passed through to API Gateway, which validates it at import time.
The following example defines a resource policy that allows any principal to invoke the API except for requests from the specified source IP address block:
$version: "2"
namespace smithy.example
use aws.apigateway#resourcePolicy
@resourcePolicy({
"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"
}
}
}
]
})
service Weather {
version: "2018-03-17"
}
Note
This trait should be considered internal-only and not exposed to your customers.