Amazon API Gateway traits#

Smithy can integrate with Amazon API Gateway using traits, authentication schemes, and OpenAPI specifications.

aws.apigateway#apiKeySource trait#

Summary
Specifies the source of the caller identifier that will be used to throttle API methods that require a key.
Trait selector
service
Value type

string set to one of the following values:

Value Description
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)
See also

The following example sets the X-API-Key header as the API key source.

$version: "2"

namespace smithy.example

use aws.apigateway#apiKeySource

@apiKeySource("HEADER")
service Weather {
    version: "2018-03-17"
}

Note

This trait should be considered internal-only and not exposed to your customers.

aws.apigateway#authorizers trait#

Summary
Lambda authorizers to attach to the authentication schemes defined on this service.
Trait selector

service[trait|protocols]

A service shape that has the protocols trait

Value type
map of arbitrary names to authorizer definitions. These authorizer definitions are applied to a service, resource, or operation using the aws.apigateway#authorizer trait.

An authorizer definition is a structure that supports the following members:

Property Type Description
scheme string Required. A Smithy authentication scheme shape ID that identifies how a client authenticates. This value MUST reference one of the authentication schemes attached to the service.
type string The type of the authorizer. If specifying information beyond the scheme or customAuthType, this value is required. The value must be "token", for an authorizer with the caller identity embedded in an authorization token, or "request", for an authorizer with the caller identity contained in request parameters.
customAuthType string The authType of the authorizer. This value is used in APIGateway exports as x-amazon-apigateway-authtype. This value is set to custom by default if type is set, or awsSigv4 if your scheme is aws.auth#sigv4.
uri string Specifies the authorizer's Uniform Resource Identifier (URI). For token or request authorizers, this must be a well-formed Lambda function URI, for example, arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:{account_id}:function:{lambda_function_name}/invocations. In general, the URI has this form arn:aws:apigateway:{region}:lambda:path/{service_api}, where {region} is the same as the region hosting the Lambda function, path indicates that the remaining substring in the URI should be treated as the path to the resource, including the initial /. For Lambda functions, this is usually of the form /2015-03-31/functions/[FunctionARN]/invocations.
credentials string Specifies the required credentials as an IAM role for API Gateway to invoke the authorizer. To specify an IAM role for API Gateway to assume, use the role's Amazon Resource Name (ARN). This value MUST be omitted in order to use resource-based permissions on the Lambda function.
identitySource string

The identity source for which authorization is requested.

For a token or cognito_user_pools authorizer, this is required and specifies the request header mapping expression for the custom header holding the authorization token submitted by the client. For example, if the token header name is Auth, the header mapping expression is method.request.header.Auth.

For the request authorizer, this is required when authorization caching is enabled. The value is a comma-separated string of one or more mapping expressions of the specified request parameters. For example, if an Auth header and a Name query string parameter are defined as identity sources, this value is method.request.header.Auth, method.request.querystring.Name. These parameters will be used to derive the authorization caching key and to perform runtime validation of the request authorizer by verifying all of the identity-related request parameters are present, not null and non-empty. Only when this is true does the authorizer invoke the authorizer Lambda function, otherwise, it returns a 401 Unauthorized response without calling the Lambda function. The valid value is a string of comma-separated mapping expressions of the specified request parameters. When the authorization caching is not enabled, this property is optional.
identityValidationExpression string A validation expression for the incoming identity token. For token authorizers, this value is a regular expression. API Gateway will match the aud field of the incoming token from the client against the specified regular expression. It will invoke the authorizer's Lambda function when there is a match. Otherwise, it will return a 401 Unauthorized response without calling the Lambda function. The validation expression does not apply to the request authorizer.
resultTtlInSeconds integer The TTL in seconds of cached authorizer results. If it equals 0, authorization caching is disabled. If it is greater than 0, API Gateway will cache authorizer responses. If this field is not set, the default value is 300. The maximum value is 3600, or 1 hour.
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. Supported values are 1.0 and 2.0. For more information, see Lambda Authorizers 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. 
$version: "2"

namespace ns.foo

use aws.apigateway#authorizer
use aws.apigateway#authorizers
use aws.auth#sigv4
use aws.protocols#restJson1

@restJson1
@sigv4(name: "weather")
@authorizer("arbitrary-name")
@authorizers(
    "arbitrary-name": {
        scheme: sigv4
        type: "request"
        uri: "arn:foo:baz"
        credentials: "arn:foo:bar"
        identitySource: "mapping.expression"
        identityValidationExpression: "[A-Z]+"
        resultTtlInSeconds: 100
        authorizerPayloadFormatVersion: "2.0"
        enableSimpleResponses: true
    }
)
service Weather {
    version: "2018-03-17"
}

Note

This trait should be considered internal-only and not exposed to your customers.

aws.apigateway#authorizer trait#

Summary
Applies a Lambda authorizer to a service, resource, or operation. Authorizers are resolved hierarchically: an operation inherits the effective authorizer applied to a parent resource or operation.
Trait selector

:is(service, resource, operation)

A service, resource, or operation

Value type
string value that MUST reference one of the keys in the aws.apigateway#authorizers trait of the service that contains the shape.

Note

This trait should be considered internal-only and not exposed to your customers.

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

string value set to one of the following:

Value Description
full The parameters and body of a request are validated.
params-only Only the parameters of a request are validated.
body-only Only the body of a request is validated.
See also

Then 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.

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

The aws.apigateway#integration trait is a structure that supports the following members:

Property Type Description
type string

Required. The type of integration with the specified backend. Valid values are:

  • http or http_proxy: for integration with an HTTP backend
  • aws_proxy: for integration with AWS Lambda functions
  • aws: for integration with AWS Lambda functions or other AWS services such as Amazon DynamoDB, Amazon Simple Notification Service or Amazon Simple Queue Service.
uri string Required. 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.
httpMethod string Required. Specifies the integration's HTTP method type (for example, POST). For Lambda function invocations, the value must be POST.
credentials string 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 string Specifies how a request payload of unmapped content type is passed through the integration request without modification. Supported values are when_no_templates, when_no_match, and never. For more information, see Integration.passthroughBehavior.
contentHandling ContentHandling string Request payload content handling.
timeoutInMillis integer Integration timeouts between 50 ms and 29,000 ms.
connectionId string The ID of a VpcLink for the private integration.
connectionType string The type of the network connection to the integration endpoint. The valid value is INTERNET for connections through the public routable internet or VPC_LINK for private connections between API Gateway and a network load balancer in a VPC. The default value is INTERNET.
cacheNamespace string An API-specific tag group of related cached parameters.
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.
cacheKeyParameters list<string> A list of request parameter names whose values are to be cached.
requestParameters map of requestParameters structure to request parameters Specifies mappings from method request parameters to integration request parameters. Supported request parameters are querystring, path, header, and body.
requestTemplates map of media types to requestTemplates structure Mapping templates for a request payload of specified media types.
responses map of response codes to responses structure 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 string Specifies how a request payload of unmapped content type is passed through the integration request without modification. Supported values are when_no_templates, when_no_match, and never. For more information, see Integration.passthroughBehavior.
requestParameters map of requestParameters structure to request parameters Specifies mappings from method request parameters to integration request parameters. Supported request parameters are querystring, path, header, and body.
requestTemplates map of media types to requestTemplates structure Mapping templates for a request payload of specified media types.
responses map of response codes to responses structure 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.

Shared trait data types#

The following shapes are used throughout the Smithy API Gateway traits definitions.

ContentHandling string#

Defines the payload conversion handling of a request or response. Valid values are:

  • CONVERT_TO_TEXT: 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
  • CONVERT_TO_BINARY: for converting a text payload into Base64-decoded blob or passing through a binary payload natively without modification.

requestParameters structure#

Specifies mappings from named method request parameters to integration request parameters. The method request parameters must be defined before they are referenced.

Properties

Property Type Description
integration.request.<param-type>.<param-name> string The value must be a predefined method request parameter of the method.request.<param-type>.<param-name> format, where <param-type> can be querystring, path, header, or body. For the body parameter, the <param-name> is a JSON path expression without the $. prefix.

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.

{
    "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"
    }
}

requestTemplates structure#

Specifies mapping templates for a request payload of the specified media types.

Properties

Property Type Description
<Media type> string A mapping templates.

The following example sets mapping templates for a request payload of the application/json and application/xml media types.

{
    "requestTemplates" : {
        "application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
        "application/xml" : "#set ($root=$input.path('$')) <stage>$root.name</stage> "
    }
}

responses structure#

Defines the method's responses and specifies parameter mappings or payload mappings from integration responses to method responses.

Properties

Property Type Description
<Response status pattern> Response structure

Selection regular expression used to match the integration response to the method response. For HTTP integrations, this 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.

Note

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 resource in the API Gateway REST API.

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 media 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('$')) <stage>$root.name</stage> "
            }
        },
        "302" : {
            "statusCode" : "302",
            "responseParameters" : {
                "method.response.header.Location": "integration.response.body.redirect.url"
            }
        }
    }
}

response structure#

Defines a response and specifies parameter mappings or payload mappings from the integration response to the method response.

Properties

Property 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 responses field.
responseTemplates Response templates structure Specifies media type-specific mapping templates for the response's payload.
responseParameters Response parameters structure 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 ContentHandling string Response payload content handling.

The following example defines a 302 response for the method that derives a payload of the application/json or application/xml media 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('$')) <stage>$root.name</stage> "
    },
    "responseParameters" : {
        "method.response.header.Location": "integration.response.body.redirect.url"
    }
}

Response templates structure#

Specifies mapping templates for a response payload of the specified media types.

Properties

Property Type Description
<Media type> string Specifies a mapping template to transform the integration response body to the method response body for a given media type. For information about creating a mapping template, see mapping templates. An example of a media type is application/json.

The following example sets mapping templates for a request payload of the application/json and application/xml media types.

{
    "responseTemplates" : {
        "application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
        "application/xml" : "#set ($root=$input.path('$')) <stage>$root.name</stage> "
    }
}

Response parameters structure#

Specifies mappings from integration method response parameters to method response parameters. Only the header and body types of the integration response parameters can be mapped to the header type of the method response.

Properties

Property Type Description
method.response.header.<param-name> string The named parameter value can be derived from the header and body types of the integration response parameters only.

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"
    }
}