Package software.amazon.awscdk.services.apigateway
Amazon API Gateway Construct Library
---
AWS CDK v1 has reached End-of-Support on 2023-06-01. This package is no longer being updated, and users should migrate to AWS CDK v2.
For more information on how to migrate, see the Migrating to AWS CDK v2 guide.
Amazon API Gateway is a fully managed service that makes it easy for developers to publish, maintain, monitor, and secure APIs at any scale. Create an API to access data, business logic, or functionality from your back-end services, such as applications running on Amazon Elastic Compute Cloud (Amazon EC2), code running on AWS Lambda, or any web application.
Table of Contents
- Defining APIs
- AWS Lambda-backed APIs
- AWS StepFunctions backed APIs
- Integration Targets
- Usage Plan & API Keys
- Working with models
- Default Integration and Method Options
- Proxy Routes
- Authorizers
- Mutual TLS
- Deployments
- Custom Domains
- Access Logging
- Cross Origin Resource Sharing (CORS)
- Endpoint Configuration
- Private Integrations
- Gateway Response
- OpenAPI Definition
- Metrics
- APIGateway v2
Defining APIs
APIs are defined as a hierarchy of resources and methods. addResource
and
addMethod
can be used to build this hierarchy. The root resource is
api.root
.
For example, the following code defines an API that includes the following HTTP
endpoints: ANY /
, GET /books
, POST /books
, GET /books/{book_id}
, DELETE /books/{book_id}
.
RestApi api = new RestApi(this, "books-api"); api.root.addMethod("ANY"); Resource books = api.root.addResource("books"); books.addMethod("GET"); books.addMethod("POST"); Resource book = books.addResource("{book_id}"); book.addMethod("GET"); book.addMethod("DELETE");
AWS Lambda-backed APIs
A very common practice is to use Amazon API Gateway with AWS Lambda as the
backend integration. The LambdaRestApi
construct makes it easy:
The following code defines a REST API that routes all requests to the specified AWS Lambda function:
Function backend; LambdaRestApi.Builder.create(this, "myapi") .handler(backend) .build();
You can also supply proxy: false
, in which case you will have to explicitly
define the API model:
Function backend; LambdaRestApi api = LambdaRestApi.Builder.create(this, "myapi") .handler(backend) .proxy(false) .build(); Resource items = api.root.addResource("items"); items.addMethod("GET"); // GET /items items.addMethod("POST"); // POST /items Resource item = items.addResource("{item}"); item.addMethod("GET"); // GET /items/{item} // the default integration for methods is "handler", but one can // customize this behavior per method or even a sub path. item.addMethod("DELETE", new HttpIntegration("http://amazon.com"));
AWS StepFunctions backed APIs
You can use Amazon API Gateway with AWS Step Functions as the backend integration, specifically Synchronous Express Workflows.
The StepFunctionsRestApi
only supports integration with Synchronous Express state machine. The StepFunctionsRestApi
construct makes this easy by setting up input, output and error mapping.
The construct sets up an API endpoint and maps the ANY
HTTP method and any calls to the API endpoint starts an express workflow execution for the underlying state machine.
Invoking the endpoint with any HTTP method (GET
, POST
, PUT
, DELETE
, ...) in the example below will send the request to the state machine as a new execution. On success, an HTTP code 200
is returned with the execution output as the Response Body.
If the execution fails, an HTTP 500
response is returned with the error
and cause
from the execution output as the Response Body. If the request is invalid (ex. bad execution input) HTTP code 400
is returned.
The response from the invocation contains only the output
field from the
StartSyncExecution API.
In case of failures, the fields error
and cause
are returned as part of the response.
Other metadata such as billing details, AWS account ID and resource ARNs are not returned in the API response.
By default, a prod
stage is provisioned.
In order to reduce the payload size sent to AWS Step Functions, headers
are not forwarded to the Step Functions execution input. It is possible to choose whether headers
, requestContext
, path
, querystring
, and authorizer
are included or not. By default, headers
are excluded in all requests.
More details about AWS Step Functions payload limit can be found at https://docs.aws.amazon.com/step-functions/latest/dg/limits-overview.html#service-limits-task-executions.
The following code defines a REST API that routes all requests to the specified AWS StepFunctions state machine:
Pass stateMachineDefinition = new Pass(this, "PassState"); IStateMachine stateMachine = StateMachine.Builder.create(this, "StateMachine") .definition(stateMachineDefinition) .stateMachineType(StateMachineType.EXPRESS) .build(); StepFunctionsRestApi.Builder.create(this, "StepFunctionsRestApi") .deploy(true) .stateMachine(stateMachine) .build();
When the REST API endpoint configuration above is invoked using POST, as follows -
curl -X POST -d '{ "customerId": 1 }' https://example.com/
AWS Step Functions will receive the request body in its input as follows:
{ "body": { "customerId": 1 }, "path": "/", "querystring": {} }
When the endpoint is invoked at path '/users/5' using the HTTP GET method as below:
curl -X GET https://example.com/users/5?foo=bar
AWS Step Functions will receive the following execution input:
{ "body": {}, "path": { "users": "5" }, "querystring": { "foo": "bar" } }
Additional information around the request such as the request context, authorizer context, and headers can be included as part of the input forwarded to the state machine. The following example enables headers to be included in the input but not query string.
StepFunctionsRestApi.Builder.create(this, "StepFunctionsRestApi") .stateMachine(machine) .headers(true) .path(false) .querystring(false) .authorizer(false) .requestContext(RequestContext.builder() .caller(true) .user(true) .build()) .build();
In such a case, when the endpoint is invoked as below:
curl -X GET https://example.com/
AWS Step Functions will receive the following execution input:
{ "headers": { "Accept": "...", "CloudFront-Forwarded-Proto": "...", }, "requestContext": { "accountId": "...", "apiKey": "...", }, "body": {} }
Breaking up Methods and Resources across Stacks
It is fairly common for REST APIs with a large number of Resources and Methods to hit the CloudFormation limit of 500 resources per stack.
To help with this, Resources and Methods for the same REST API can be re-organized across multiple stacks. A common way to do this is to have a stack per Resource or groups of Resources, but this is not the only possible way. The following example uses sets up two Resources '/pets' and '/books' in separate stacks using nested stacks:
import software.amazon.awscdk.core.App; import software.amazon.awscdk.core.CfnOutput; import software.amazon.awscdk.core.NestedStack; import software.amazon.awscdk.core.NestedStackProps; import software.amazon.awscdk.core.Stack; import software.constructs.Construct; import software.amazon.awscdk.services.apigateway.Deployment; import software.amazon.awscdk.services.apigateway.Method; import software.amazon.awscdk.services.apigateway.MockIntegration; import software.amazon.awscdk.services.apigateway.PassthroughBehavior; import software.amazon.awscdk.services.apigateway.RestApi; import software.amazon.awscdk.services.apigateway.Stage; /** * This file showcases how to split up a RestApi's Resources and Methods across nested stacks. * * The root stack 'RootStack' first defines a RestApi. * Two nested stacks BooksStack and PetsStack, create corresponding Resources '/books' and '/pets'. * They are then deployed to a 'prod' Stage via a third nested stack - DeployStack. * * To verify this worked, go to the APIGateway */ public class RootStack extends Stack { public RootStack(Construct scope) { super(scope, "integ-restapi-import-RootStack"); RestApi restApi = RestApi.Builder.create(this, "RestApi") .deploy(false) .build(); restApi.root.addMethod("ANY"); PetsStack petsStack = new PetsStack(this, new ResourceNestedStackProps() .restApiId(restApi.getRestApiId()) .rootResourceId(restApi.getRestApiRootResourceId()) ); BooksStack booksStack = new BooksStack(this, new ResourceNestedStackProps() .restApiId(restApi.getRestApiId()) .rootResourceId(restApi.getRestApiRootResourceId()) ); new DeployStack(this, new DeployStackProps() .restApiId(restApi.getRestApiId()) .methods(petsStack.methods.concat(booksStack.getMethods())) ); CfnOutput.Builder.create(this, "PetsURL") .value(String.format("https://%s.execute-api.%s.amazonaws.com/prod/pets", restApi.getRestApiId(), this.region)) .build(); CfnOutput.Builder.create(this, "BooksURL") .value(String.format("https://%s.execute-api.%s.amazonaws.com/prod/books", restApi.getRestApiId(), this.region)) .build(); } } public class ResourceNestedStackProps extends NestedStackProps { private String restApiId; public String getRestApiId() { return this.restApiId; } public ResourceNestedStackProps restApiId(String restApiId) { this.restApiId = restApiId; return this; } private String rootResourceId; public String getRootResourceId() { return this.rootResourceId; } public ResourceNestedStackProps rootResourceId(String rootResourceId) { this.rootResourceId = rootResourceId; return this; } } public class PetsStack extends NestedStack { public final Method[] methods; public PetsStack(Construct scope, ResourceNestedStackProps props) { super(scope, "integ-restapi-import-PetsStack", props); IRestApi api = RestApi.fromRestApiAttributes(this, "RestApi", RestApiAttributes.builder() .restApiId(props.getRestApiId()) .rootResourceId(props.getRootResourceId()) .build()); Method method = api.root.addResource("pets").addMethod("GET", MockIntegration.Builder.create() .integrationResponses(List.of(IntegrationResponse.builder() .statusCode("200") .build())) .passthroughBehavior(PassthroughBehavior.NEVER) .requestTemplates(Map.of( "application/json", "{ \"statusCode\": 200 }")) .build(), MethodOptions.builder() .methodResponses(List.of(MethodResponse.builder().statusCode("200").build())) .build()); this.methods.push(method); } } public class BooksStack extends NestedStack { public final Method[] methods; public BooksStack(Construct scope, ResourceNestedStackProps props) { super(scope, "integ-restapi-import-BooksStack", props); IRestApi api = RestApi.fromRestApiAttributes(this, "RestApi", RestApiAttributes.builder() .restApiId(props.getRestApiId()) .rootResourceId(props.getRootResourceId()) .build()); Method method = api.root.addResource("books").addMethod("GET", MockIntegration.Builder.create() .integrationResponses(List.of(IntegrationResponse.builder() .statusCode("200") .build())) .passthroughBehavior(PassthroughBehavior.NEVER) .requestTemplates(Map.of( "application/json", "{ \"statusCode\": 200 }")) .build(), MethodOptions.builder() .methodResponses(List.of(MethodResponse.builder().statusCode("200").build())) .build()); this.methods.push(method); } } public class DeployStackProps extends NestedStackProps { private String restApiId; public String getRestApiId() { return this.restApiId; } public DeployStackProps restApiId(String restApiId) { this.restApiId = restApiId; return this; } private Method[] methods; public Method[] getMethods() { return this.methods; } public DeployStackProps methods(Method[] methods) { this.methods = methods; return this; } } public class DeployStack extends NestedStack { public DeployStack(Construct scope, DeployStackProps props) { super(scope, "integ-restapi-import-DeployStack", props); Deployment deployment = Deployment.Builder.create(this, "Deployment") .api(RestApi.fromRestApiId(this, "RestApi", props.getRestApiId())) .build(); if (props.getMethods()) { for (Object method : props.getMethods()) { deployment.node.addDependency(method); } } Stage.Builder.create(this, "Stage").deployment(deployment).build(); } } new RootStack(new App());
Integration Targets
Methods are associated with backend integrations, which are invoked when this method is called. API Gateway supports the following integrations:
MockIntegration
- can be used to test APIs. This is the default integration if one is not specified.LambdaIntegration
- can be used to invoke an AWS Lambda function.AwsIntegration
- can be used to invoke arbitrary AWS service APIs.HttpIntegration
- can be used to invoke HTTP endpoints.
The following example shows how to integrate the GET /book/{book_id}
method to
an AWS Lambda function:
Function getBookHandler; Resource book; LambdaIntegration getBookIntegration = new LambdaIntegration(getBookHandler); book.addMethod("GET", getBookIntegration);
Integration options can be optionally be specified:
Function getBookHandler; LambdaIntegration getBookIntegration; LambdaIntegration getBookIntegration = LambdaIntegration.Builder.create(getBookHandler) .contentHandling(ContentHandling.CONVERT_TO_TEXT) // convert to base64 .credentialsPassthrough(true) .build();
Method options can optionally be specified when adding methods:
Resource book; LambdaIntegration getBookIntegration; book.addMethod("GET", getBookIntegration, MethodOptions.builder() .authorizationType(AuthorizationType.IAM) .apiKeyRequired(true) .build());
It is possible to also integrate with AWS services in a different region. The following code integrates with Amazon SQS in the
eu-west-1
region.
AwsIntegration getMessageIntegration = AwsIntegration.Builder.create() .service("sqs") .path("queueName") .region("eu-west-1") .build();
Usage Plan & API Keys
A usage plan specifies who can access one or more deployed API stages and methods, and the rate at which they can be accessed. The plan uses API keys to identify API clients and meters access to the associated API stages for each key. Usage plans also allow configuring throttling limits and quota limits that are enforced on individual client API keys.
The following example shows how to create and asscociate a usage plan and an API key:
LambdaIntegration integration; RestApi api = new RestApi(this, "hello-api"); Resource v1 = api.root.addResource("v1"); Resource echo = v1.addResource("echo"); Method echoMethod = echo.addMethod("GET", integration, MethodOptions.builder().apiKeyRequired(true).build()); UsagePlan plan = api.addUsagePlan("UsagePlan", UsagePlanProps.builder() .name("Easy") .throttle(ThrottleSettings.builder() .rateLimit(10) .burstLimit(2) .build()) .build()); IApiKey key = api.addApiKey("ApiKey"); plan.addApiKey(key);
To associate a plan to a given RestAPI stage:
UsagePlan plan; RestApi api; Method echoMethod; plan.addApiStage(UsagePlanPerApiStage.builder() .stage(api.getDeploymentStage()) .throttle(List.of(ThrottlingPerMethod.builder() .method(echoMethod) .throttle(ThrottleSettings.builder() .rateLimit(10) .burstLimit(2) .build()) .build())) .build());
Existing usage plans can be imported into a CDK app using its id.
IUsagePlan importedUsagePlan = UsagePlan.fromUsagePlanId(this, "imported-usage-plan", "<usage-plan-key-id>");
The name and value of the API Key can be specified at creation; if not provided, a name and value will be automatically generated by API Gateway.
RestApi api; IApiKey key = api.addApiKey("ApiKey", ApiKeyOptions.builder() .apiKeyName("myApiKey1") .value("MyApiKeyThatIsAtLeast20Characters") .build());
Existing API keys can also be imported into a CDK app using its id.
IApiKey importedKey = ApiKey.fromApiKeyId(this, "imported-key", "<api-key-id>");
The "grant" methods can be used to give prepackaged sets of permissions to other resources. The following code provides read permission to an API key.
ApiKey importedKey; Function lambdaFn; importedKey.grantRead(lambdaFn);
⚠️ Multiple API Keys
It is possible to specify multiple API keys for a given Usage Plan, by calling usagePlan.addApiKey()
.
When using multiple API keys, a past bug of the CDK prevents API key associations to a Usage Plan to be deleted.
If the CDK app had the feature flag - @aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId
- enabled when the API
keys were created, then the app will not be affected by this bug.
If this is not the case, you will need to ensure that the CloudFormation logical ids of the API keys that are not
being deleted remain unchanged.
Make note of the logical ids of these API keys before removing any, and set it as part of the addApiKey()
method:
UsagePlan usageplan; ApiKey apiKey; usageplan.addApiKey(apiKey, AddApiKeyOptions.builder() .overrideLogicalId("...") .build());
Rate Limited API Key
In scenarios where you need to create a single api key and configure rate limiting for it, you can use RateLimitedApiKey
.
This construct lets you specify rate limiting properties which should be applied only to the api key being created.
The API key created has the specified rate limits, such as quota and throttles, applied.
The following example shows how to use a rate limited api key :
RestApi api; RateLimitedApiKey key = RateLimitedApiKey.Builder.create(this, "rate-limited-api-key") .customerId("hello-customer") .resources(List.of(api)) .quota(QuotaSettings.builder() .limit(10000) .period(Period.MONTH) .build()) .build();
Working with models
When you work with Lambda integrations that are not Proxy integrations, you have to define your models and mappings for the request, response, and integration.
Function hello = Function.Builder.create(this, "hello") .runtime(Runtime.NODEJS_14_X) .handler("hello.handler") .code(Code.fromAsset("lambda")) .build(); RestApi api = RestApi.Builder.create(this, "hello-api").build(); Resource resource = api.root.addResource("v1");
You can define more parameters on the integration to tune the behavior of API Gateway
Function hello; LambdaIntegration integration = LambdaIntegration.Builder.create(hello) .proxy(false) .requestParameters(Map.of( // You can define mapping parameters from your method to your integration // - Destination parameters (the key) are the integration parameters (used in mappings) // - Source parameters (the value) are the source request parameters or expressions // @see: https://docs.aws.amazon.com/apigateway/latest/developerguide/request-response-data-mappings.html "integration.request.querystring.who", "method.request.querystring.who")) .allowTestInvoke(true) .requestTemplates(Map.of( // You can define a mapping that will build a payload for your integration, based // on the integration parameters that you have specified // Check: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html "application/json", JSON.stringify(Map.of("action", "sayHello", "pollId", "$util.escapeJavaScript($input.params('who'))")))) // This parameter defines the behavior of the engine is no suitable response template is found .passthroughBehavior(PassthroughBehavior.NEVER) .integrationResponses(List.of(IntegrationResponse.builder() // Successful response from the Lambda function, no filter defined // - the selectionPattern filter only tests the error message // We will set the response status code to 200 .statusCode("200") .responseTemplates(Map.of( // This template takes the "message" result from the Lambda function, and embeds it in a JSON response // Check https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html "application/json", JSON.stringify(Map.of("state", "ok", "greeting", "$util.escapeJavaScript($input.body)")))) .responseParameters(Map.of( // We can map response parameters // - Destination parameters (the key) are the response parameters (used in mappings) // - Source parameters (the value) are the integration response parameters or expressions "method.response.header.Content-Type", "'application/json'", "method.response.header.Access-Control-Allow-Origin", "'*'", "method.response.header.Access-Control-Allow-Credentials", "'true'")) .build(), IntegrationResponse.builder() // For errors, we check if the error message is not empty, get the error data .selectionPattern("(\n|.)+") // We will set the response status code to 200 .statusCode("400") .responseTemplates(Map.of( "application/json", JSON.stringify(Map.of("state", "error", "message", "$util.escapeJavaScript($input.path('$.errorMessage'))")))) .responseParameters(Map.of( "method.response.header.Content-Type", "'application/json'", "method.response.header.Access-Control-Allow-Origin", "'*'", "method.response.header.Access-Control-Allow-Credentials", "'true'")) .build())) .build();
You can define models for your responses (and requests)
RestApi api; // We define the JSON Schema for the transformed valid response Model responseModel = api.addModel("ResponseModel", ModelOptions.builder() .contentType("application/json") .modelName("ResponseModel") .schema(JsonSchema.builder() .schema(JsonSchemaVersion.DRAFT4) .title("pollResponse") .type(JsonSchemaType.OBJECT) .properties(Map.of( "state", JsonSchema.builder().type(JsonSchemaType.STRING).build(), "greeting", JsonSchema.builder().type(JsonSchemaType.STRING).build())) .build()) .build()); // We define the JSON Schema for the transformed error response Model errorResponseModel = api.addModel("ErrorResponseModel", ModelOptions.builder() .contentType("application/json") .modelName("ErrorResponseModel") .schema(JsonSchema.builder() .schema(JsonSchemaVersion.DRAFT4) .title("errorResponse") .type(JsonSchemaType.OBJECT) .properties(Map.of( "state", JsonSchema.builder().type(JsonSchemaType.STRING).build(), "message", JsonSchema.builder().type(JsonSchemaType.STRING).build())) .build()) .build());
And reference all on your method definition.
LambdaIntegration integration; Resource resource; Model responseModel; Model errorResponseModel; resource.addMethod("GET", integration, MethodOptions.builder() // We can mark the parameters as required .requestParameters(Map.of( "method.request.querystring.who", true)) // we can set request validator options like below .requestValidatorOptions(RequestValidatorOptions.builder() .requestValidatorName("test-validator") .validateRequestBody(true) .validateRequestParameters(false) .build()) .methodResponses(List.of(MethodResponse.builder() // Successful response from the integration .statusCode("200") // Define what parameters are allowed or not .responseParameters(Map.of( "method.response.header.Content-Type", true, "method.response.header.Access-Control-Allow-Origin", true, "method.response.header.Access-Control-Allow-Credentials", true)) // Validate the schema on the response .responseModels(Map.of( "application/json", responseModel)) .build(), MethodResponse.builder() // Same thing for the error responses .statusCode("400") .responseParameters(Map.of( "method.response.header.Content-Type", true, "method.response.header.Access-Control-Allow-Origin", true, "method.response.header.Access-Control-Allow-Credentials", true)) .responseModels(Map.of( "application/json", errorResponseModel)) .build())) .build());
Specifying requestValidatorOptions
automatically creates the RequestValidator construct with the given options.
However, if you have your RequestValidator already initialized or imported, use the requestValidator
option instead.
Default Integration and Method Options
The defaultIntegration
and defaultMethodOptions
properties can be used to
configure a default integration at any resource level. These options will be
used when defining method under this resource (recursively) with undefined
integration or options.
If not defined, the default integration is
MockIntegration
. See reference documentation for default method options.
The following example defines the booksBackend
integration as a default
integration. This means that all API methods that do not explicitly define an
integration will be routed to this AWS Lambda function.
LambdaIntegration booksBackend; RestApi api = RestApi.Builder.create(this, "books") .defaultIntegration(booksBackend) .build(); Resource books = api.root.addResource("books"); books.addMethod("GET"); // integrated with `booksBackend` books.addMethod("POST"); // integrated with `booksBackend` Resource book = books.addResource("{book_id}"); book.addMethod("GET");
A Method can be configured with authorization scopes. Authorization scopes are used in conjunction with an authorizer that uses Amazon Cognito user pools. Read more about authorization scopes here.
Authorization scopes for a Method can be configured using the authorizationScopes
property as shown below -
Resource books; books.addMethod("GET", new HttpIntegration("http://amazon.com"), MethodOptions.builder() .authorizationType(AuthorizationType.COGNITO) .authorizationScopes(List.of("Scope1", "Scope2")) .build());
Proxy Routes
The addProxy
method can be used to install a greedy {proxy+}
resource
on a path. By default, this also installs an "ANY"
method:
Resource resource; Function handler; ProxyResource proxy = resource.addProxy(ProxyResourceOptions.builder() .defaultIntegration(new LambdaIntegration(handler)) // "false" will require explicitly adding methods on the `proxy` resource .anyMethod(true) .build());
Authorizers
API Gateway supports several different authorization types that can be used for controlling access to your REST APIs.
IAM-based authorizer
The following CDK code provides 'execute-api' permission to an IAM user, via IAM policies, for the 'GET' method on the books
resource:
Resource books; User iamUser; Method getBooks = books.addMethod("GET", new HttpIntegration("http://amazon.com"), MethodOptions.builder() .authorizationType(AuthorizationType.IAM) .build()); iamUser.attachInlinePolicy(Policy.Builder.create(this, "AllowBooks") .statements(List.of( PolicyStatement.Builder.create() .actions(List.of("execute-api:Invoke")) .effect(Effect.ALLOW) .resources(List.of(getBooks.getMethodArn())) .build())) .build());
Lambda-based token authorizer
API Gateway also allows lambda functions to be used as authorizers.
This module provides support for token-based Lambda authorizers. When a client makes a request to an API's methods configured with such an authorizer, API Gateway calls the Lambda authorizer, which takes the caller's identity as input and returns an IAM policy as output. A token-based Lambda authorizer (also called a token authorizer) receives the caller's identity in a bearer token, such as a JSON Web Token (JWT) or an OAuth token.
API Gateway interacts with the authorizer Lambda function handler by passing input and expecting the output in a specific format.
The event object that the handler is called with contains the authorizationToken
and the methodArn
from the request to the
API Gateway endpoint. The handler is expected to return the principalId
(i.e. the client identifier) and a policyDocument
stating
what the client is authorizer to perform.
See here for a detailed specification on
inputs and outputs of the Lambda handler.
The following code attaches a token-based Lambda authorizer to the 'GET' Method of the Book resource:
Function authFn; Resource books; TokenAuthorizer auth = TokenAuthorizer.Builder.create(this, "booksAuthorizer") .handler(authFn) .build(); books.addMethod("GET", new HttpIntegration("http://amazon.com"), MethodOptions.builder() .authorizer(auth) .build());
A full working example is shown below.
!cdk-integ pragma:ignore-assets
import path.*; import software.amazon.awscdk.services.lambda.*; import software.amazon.awscdk.core.App; import software.amazon.awscdk.core.Stack; import software.amazon.awscdk.services.apigateway.MockIntegration; import software.amazon.awscdk.services.apigateway.PassthroughBehavior; import software.amazon.awscdk.services.apigateway.RestApi; import software.amazon.awscdk.services.apigateway.TokenAuthorizer; /* * Stack verification steps: * * `curl -s -o /dev/null -w "%{http_code}" <url>` should return 401 * * `curl -s -o /dev/null -w "%{http_code}" -H 'Authorization: deny' <url>` should return 403 * * `curl -s -o /dev/null -w "%{http_code}" -H 'Authorization: allow' <url>` should return 200 */ App app = new App(); Stack stack = new Stack(app, "TokenAuthorizerInteg"); Function authorizerFn = Function.Builder.create(stack, "MyAuthorizerFunction") .runtime(Runtime.NODEJS_14_X) .handler("index.handler") .code(AssetCode.fromAsset(join(__dirname, "integ.token-authorizer.handler"))) .build(); RestApi restapi = new RestApi(stack, "MyRestApi"); TokenAuthorizer authorizer = TokenAuthorizer.Builder.create(stack, "MyAuthorizer") .handler(authorizerFn) .build(); restapi.root.addMethod("ANY", MockIntegration.Builder.create() .integrationResponses(List.of(IntegrationResponse.builder().statusCode("200").build())) .passthroughBehavior(PassthroughBehavior.NEVER) .requestTemplates(Map.of( "application/json", "{ \"statusCode\": 200 }")) .build(), MethodOptions.builder() .methodResponses(List.of(MethodResponse.builder().statusCode("200").build())) .authorizer(authorizer) .build());
By default, the TokenAuthorizer
looks for the authorization token in the request header with the key 'Authorization'. This can,
however, be modified by changing the identitySource
property.
Authorizers can also be passed via the defaultMethodOptions
property within the RestApi
construct or the Method
construct. Unless
explicitly overridden, the specified defaults will be applied across all Method
s across the RestApi
or across all Resource
s,
depending on where the defaults were specified.
Lambda-based request authorizer
This module provides support for request-based Lambda authorizers. When a client makes a request to an API's methods configured with such an authorizer, API Gateway calls the Lambda authorizer, which takes specified parts of the request, known as identity sources, as input and returns an IAM policy as output. A request-based Lambda authorizer (also called a request authorizer) receives the identity sources in a series of values pulled from the request, from the headers, stage variables, query strings, and the context.
API Gateway interacts with the authorizer Lambda function handler by passing input and expecting the output in a specific format.
The event object that the handler is called with contains the body of the request and the methodArn
from the request to the
API Gateway endpoint. The handler is expected to return the principalId
(i.e. the client identifier) and a policyDocument
stating
what the client is authorizer to perform.
See here for a detailed specification on
inputs and outputs of the Lambda handler.
The following code attaches a request-based Lambda authorizer to the 'GET' Method of the Book resource:
Function authFn; Resource books; RequestAuthorizer auth = RequestAuthorizer.Builder.create(this, "booksAuthorizer") .handler(authFn) .identitySources(List.of(IdentitySource.header("Authorization"))) .build(); books.addMethod("GET", new HttpIntegration("http://amazon.com"), MethodOptions.builder() .authorizer(auth) .build());
A full working example is shown below.
!cdk-integ pragma:ignore-assets
import path.*; import software.amazon.awscdk.services.lambda.*; import software.amazon.awscdk.core.App; import software.amazon.awscdk.core.Stack; import software.amazon.awscdk.services.apigateway.MockIntegration; import software.amazon.awscdk.services.apigateway.PassthroughBehavior; import software.amazon.awscdk.services.apigateway.RestApi; import software.amazon.awscdk.services.apigateway.RequestAuthorizer; import software.amazon.awscdk.services.apigateway.IdentitySource; // Against the RestApi endpoint from the stack output, run // `curl -s -o /dev/null -w "%{http_code}" <url>` should return 401 // `curl -s -o /dev/null -w "%{http_code}" -H 'Authorization: deny' <url>?allow=yes` should return 403 // `curl -s -o /dev/null -w "%{http_code}" -H 'Authorization: allow' <url>?allow=yes` should return 200 App app = new App(); Stack stack = new Stack(app, "RequestAuthorizerInteg"); Function authorizerFn = Function.Builder.create(stack, "MyAuthorizerFunction") .runtime(Runtime.NODEJS_14_X) .handler("index.handler") .code(AssetCode.fromAsset(join(__dirname, "integ.request-authorizer.handler"))) .build(); RestApi restapi = new RestApi(stack, "MyRestApi"); RequestAuthorizer authorizer = RequestAuthorizer.Builder.create(stack, "MyAuthorizer") .handler(authorizerFn) .identitySources(List.of(IdentitySource.header("Authorization"), IdentitySource.queryString("allow"))) .build(); restapi.root.addMethod("ANY", MockIntegration.Builder.create() .integrationResponses(List.of(IntegrationResponse.builder().statusCode("200").build())) .passthroughBehavior(PassthroughBehavior.NEVER) .requestTemplates(Map.of( "application/json", "{ \"statusCode\": 200 }")) .build(), MethodOptions.builder() .methodResponses(List.of(MethodResponse.builder().statusCode("200").build())) .authorizer(authorizer) .build());
By default, the RequestAuthorizer
does not pass any kind of information from the request. This can,
however, be modified by changing the identitySource
property, and is required when specifying a value for caching.
Authorizers can also be passed via the defaultMethodOptions
property within the RestApi
construct or the Method
construct. Unless
explicitly overridden, the specified defaults will be applied across all Method
s across the RestApi
or across all Resource
s,
depending on where the defaults were specified.
Cognito User Pools authorizer
API Gateway also allows Amazon Cognito user pools as authorizer
The following snippet configures a Cognito user pool as an authorizer:
Resource books; UserPool userPool = new UserPool(this, "UserPool"); CognitoUserPoolsAuthorizer auth = CognitoUserPoolsAuthorizer.Builder.create(this, "booksAuthorizer") .cognitoUserPools(List.of(userPool)) .build(); books.addMethod("GET", new HttpIntegration("http://amazon.com"), MethodOptions.builder() .authorizer(auth) .authorizationType(AuthorizationType.COGNITO) .build());
Mutual TLS (mTLS)
Mutual TLS can be configured to limit access to your API based by using client certificates instead of (or as an extension of) using authorization headers.
Object acm; DomainName.Builder.create(this, "domain-name") .domainName("example.com") .certificate(acm.Certificate.fromCertificateArn(this, "cert", "arn:aws:acm:us-east-1:1111111:certificate/11-3336f1-44483d-adc7-9cd375c5169d")) .mtls(MTLSConfig.builder() .bucket(new Bucket(this, "bucket")) .key("truststore.pem") .version("version") .build()) .build();
Instructions for configuring your trust store can be found here.
Deployments
By default, the RestApi
construct will automatically create an API Gateway
Deployment and a "prod" Stage which represent the API configuration you
defined in your CDK app. This means that when you deploy your app, your API will
be have open access from the internet via the stage URL.
The URL of your API can be obtained from the attribute restApi.url
, and is
also exported as an Output
from your stack, so it's printed when you cdk deploy
your app:
$ cdk deploy ... books.booksapiEndpointE230E8D5 = https://6lyktd4lpk.execute-api.us-east-1.amazonaws.com/prod/
To disable this behavior, you can set { deploy: false }
when creating your
API. This means that the API will not be deployed and a stage will not be
created for it. You will need to manually define a apigateway.Deployment
and
apigateway.Stage
resources.
Use the deployOptions
property to customize the deployment options of your
API.
The following example will configure API Gateway to emit logs and data traces to AWS CloudWatch for all API calls:
By default, an IAM role will be created and associated with API Gateway to allow it to write logs and metrics to AWS CloudWatch unless
cloudWatchRole
is set tofalse
.
RestApi api = RestApi.Builder.create(this, "books") .deployOptions(StageOptions.builder() .loggingLevel(MethodLoggingLevel.INFO) .dataTraceEnabled(true) .build()) .build();
Deep dive: Invalidation of deployments
API Gateway deployments are an immutable snapshot of the API. This means that we want to automatically create a new deployment resource every time the API model defined in our CDK app changes.
In order to achieve that, the AWS CloudFormation logical ID of the
AWS::ApiGateway::Deployment
resource is dynamically calculated by hashing the
API configuration (resources, methods). This means that when the configuration
changes (i.e. a resource or method are added, configuration is changed), a new
logical ID will be assigned to the deployment resource. This will cause
CloudFormation to create a new deployment resource.
By default, old deployments are deleted. You can set retainDeployments: true
to allow users revert the stage to an old deployment manually.
Custom Domains
To associate an API with a custom domain, use the domainName
configuration when
you define your API:
Object acmCertificateForExampleCom; RestApi api = RestApi.Builder.create(this, "MyDomain") .domainName(DomainNameOptions.builder() .domainName("example.com") .certificate(acmCertificateForExampleCom) .build()) .build();
This will define a DomainName
resource for you, along with a BasePathMapping
from the root of the domain to the deployment stage of the API. This is a common
set up.
To route domain traffic to an API Gateway API, use Amazon Route 53 to create an
alias record. An alias record is a Route 53 extension to DNS. It's similar to a
CNAME record, but you can create an alias record both for the root domain, such
as example.com
, and for subdomains, such as www.example.com
. (You can create
CNAME records only for subdomains.)
import software.amazon.awscdk.services.route53.*; import software.amazon.awscdk.services.route53.targets.*; RestApi api; Object hostedZoneForExampleCom; ARecord.Builder.create(this, "CustomDomainAliasRecord") .zone(hostedZoneForExampleCom) .target(RecordTarget.fromAlias(new ApiGateway(api))) .build();
You can also define a DomainName
resource directly in order to customize the default behavior:
Object acmCertificateForExampleCom; DomainName.Builder.create(this, "custom-domain") .domainName("example.com") .certificate(acmCertificateForExampleCom) .endpointType(EndpointType.EDGE) // default is REGIONAL .securityPolicy(SecurityPolicy.TLS_1_2) .build();
Once you have a domain, you can map base paths of the domain to APIs.
The following example will map the URL https://example.com/go-to-api1
to the api1
API and https://example.com/boom to the api2
API.
DomainName domain; RestApi api1; RestApi api2; domain.addBasePathMapping(api1, BasePathMappingOptions.builder().basePath("go-to-api1").build()); domain.addBasePathMapping(api2, BasePathMappingOptions.builder().basePath("boom").build());
You can specify the API Stage
to which this base path URL will map to. By default, this will be the
deploymentStage
of the RestApi
.
DomainName domain; RestApi restapi; Deployment betaDeploy = Deployment.Builder.create(this, "beta-deployment") .api(restapi) .build(); Stage betaStage = Stage.Builder.create(this, "beta-stage") .deployment(betaDeploy) .build(); domain.addBasePathMapping(restapi, BasePathMappingOptions.builder().basePath("api/beta").stage(betaStage).build());
If you don't specify basePath
, all URLs under this domain will be mapped
to the API, and you won't be able to map another API to the same domain:
DomainName domain; RestApi api; domain.addBasePathMapping(api);
This can also be achieved through the mapping
configuration when defining the
domain as demonstrated above.
If you wish to setup this domain with an Amazon Route53 alias, use the targets.ApiGatewayDomain
:
Object hostedZoneForExampleCom; DomainName domainName; import software.amazon.awscdk.services.route53.*; import software.amazon.awscdk.services.route53.targets.*; ARecord.Builder.create(this, "CustomDomainAliasRecord") .zone(hostedZoneForExampleCom) .target(RecordTarget.fromAlias(new ApiGatewayDomain(domainName))) .build();
Access Logging
Access logging creates logs every time an API method is accessed. Access logs can have information on who has accessed the API, how the caller accessed the API and what responses were generated. Access logs are configured on a Stage of the RestApi. Access logs can be expressed in a format of your choosing, and can contain any access details, with a minimum that it must include the 'requestId'. The list of variables that can be expressed in the access log can be found here. Read more at Setting Up CloudWatch API Logging in API Gateway
// production stage LogGroup prdLogGroup = new LogGroup(this, "PrdLogs"); RestApi api = RestApi.Builder.create(this, "books") .deployOptions(StageOptions.builder() .accessLogDestination(new LogGroupLogDestination(prdLogGroup)) .accessLogFormat(AccessLogFormat.jsonWithStandardFields()) .build()) .build(); Deployment deployment = Deployment.Builder.create(this, "Deployment").api(api).build(); // development stage LogGroup devLogGroup = new LogGroup(this, "DevLogs"); Stage.Builder.create(this, "dev") .deployment(deployment) .accessLogDestination(new LogGroupLogDestination(devLogGroup)) .accessLogFormat(AccessLogFormat.jsonWithStandardFields(JsonWithStandardFieldProps.builder() .caller(false) .httpMethod(true) .ip(true) .protocol(true) .requestTime(true) .resourcePath(true) .responseLength(true) .status(true) .user(true) .build())) .build();
The following code will generate the access log in the CLF format.
LogGroup logGroup = new LogGroup(this, "ApiGatewayAccessLogs"); RestApi api = RestApi.Builder.create(this, "books") .deployOptions(StageOptions.builder() .accessLogDestination(new LogGroupLogDestination(logGroup)) .accessLogFormat(AccessLogFormat.clf()) .build()) .build();
You can also configure your own access log format by using the AccessLogFormat.custom()
API.
AccessLogField
provides commonly used fields. The following code configures access log to contain.
LogGroup logGroup = new LogGroup(this, "ApiGatewayAccessLogs"); RestApi.Builder.create(this, "books") .deployOptions(StageOptions.builder() .accessLogDestination(new LogGroupLogDestination(logGroup)) .accessLogFormat(AccessLogFormat.custom(String.format("%s %s %s", AccessLogField.contextRequestId(), AccessLogField.contextErrorMessage(), AccessLogField.contextErrorMessageString()))) .build()) .build();
You can use the methodOptions
property to configure
default method throttling
for a stage. The following snippet configures the a stage that accepts
100 requests per minute, allowing burst up to 200 requests per minute.
RestApi api = new RestApi(this, "books"); Deployment deployment = Deployment.Builder.create(this, "my-deployment").api(api).build(); Stage stage = Stage.Builder.create(this, "my-stage") .deployment(deployment) .methodOptions(Map.of( "/*/*", MethodDeploymentOptions.builder() // This special path applies to all resource paths and all HTTP methods .throttlingRateLimit(100) .throttlingBurstLimit(200).build())) .build();
Configuring methodOptions
on the deployOptions
of RestApi
will set the
throttling behaviors on the default stage that is automatically created.
RestApi api = RestApi.Builder.create(this, "books") .deployOptions(StageOptions.builder() .methodOptions(Map.of( "/*/*", MethodDeploymentOptions.builder() // This special path applies to all resource paths and all HTTP methods .throttlingRateLimit(100) .throttlingBurstLimit(1000).build())) .build()) .build();
Cross Origin Resource Sharing (CORS)
Cross-Origin Resource Sharing (CORS) is a mechanism that uses additional HTTP headers to tell browsers to give a web application running at one origin, access to selected resources from a different origin. A web application executes a cross-origin HTTP request when it requests a resource that has a different origin (domain, protocol, or port) from its own.
You can add the CORS preflight OPTIONS
HTTP method to any API resource via the defaultCorsPreflightOptions
option or by calling the addCorsPreflight
on a specific resource.
The following example will enable CORS for all methods and all origins on all resources of the API:
RestApi.Builder.create(this, "api") .defaultCorsPreflightOptions(CorsOptions.builder() .allowOrigins(Cors.ALL_ORIGINS) .allowMethods(Cors.ALL_METHODS) .build()) .build();
The following example will add an OPTIONS method to the myResource
API resource, which
only allows GET and PUT HTTP requests from the origin https://amazon.com.
Resource myResource; myResource.addCorsPreflight(CorsOptions.builder() .allowOrigins(List.of("https://amazon.com")) .allowMethods(List.of("GET", "PUT")) .build());
See the
CorsOptions
API reference for a detailed list of supported configuration options.
You can specify defaults this at the resource level, in which case they will be applied to the entire resource sub-tree:
Resource resource; Resource subtree = resource.addResource("subtree", ResourceOptions.builder() .defaultCorsPreflightOptions(CorsOptions.builder() .allowOrigins(List.of("https://amazon.com")) .build()) .build());
This means that all resources under subtree
(inclusive) will have a preflight
OPTIONS added to them.
See #906 for a list of CORS features which are not yet supported.
Endpoint Configuration
API gateway allows you to specify an
API Endpoint Type.
To define an endpoint type for the API gateway, use endpointConfiguration
property:
RestApi api = RestApi.Builder.create(this, "api") .endpointConfiguration(EndpointConfiguration.builder() .types(List.of(EndpointType.EDGE)) .build()) .build();
You can also create an association between your Rest API and a VPC endpoint. By doing so, API Gateway will generate a new Route53 Alias DNS record which you can use to invoke your private APIs. More info can be found here.
Here is an example:
IVpcEndpoint someEndpoint; RestApi api = RestApi.Builder.create(this, "api") .endpointConfiguration(EndpointConfiguration.builder() .types(List.of(EndpointType.PRIVATE)) .vpcEndpoints(List.of(someEndpoint)) .build()) .build();
By performing this association, we can invoke the API gateway using the following format:
https://{rest-api-id}-{vpce-id}.execute-api.{region}.amazonaws.com/{stage}
Private Integrations
A private integration makes it simple to expose HTTP/HTTPS resources behind an
Amazon VPC for access by clients outside of the VPC. The private integration uses
an API Gateway resource of VpcLink
to encapsulate connections between API
Gateway and targeted VPC resources.
The VpcLink
is then attached to the Integration
of a specific API Gateway
Method. The following code sets up a private integration with a network load
balancer -
import software.amazon.awscdk.services.elasticloadbalancingv2.*; Vpc vpc = new Vpc(this, "VPC"); NetworkLoadBalancer nlb = NetworkLoadBalancer.Builder.create(this, "NLB") .vpc(vpc) .build(); VpcLink link = VpcLink.Builder.create(this, "link") .targets(List.of(nlb)) .build(); Integration integration = Integration.Builder.create() .type(IntegrationType.HTTP_PROXY) .options(IntegrationOptions.builder() .connectionType(ConnectionType.VPC_LINK) .vpcLink(link) .build()) .build();
The uri for the private integration, in the case of a VpcLink, will be set to the DNS name of
the VPC Link's NLB. If the VPC Link has multiple NLBs or the VPC Link is imported or the DNS
name cannot be determined for any other reason, the user is expected to specify the uri
property.
Any existing VpcLink
resource can be imported into the CDK app via the VpcLink.fromVpcLinkId()
.
IVpcLink awesomeLink = VpcLink.fromVpcLinkId(this, "awesome-vpc-link", "us-east-1_oiuR12Abd");
Gateway response
If the Rest API fails to process an incoming request, it returns to the client an error response without forwarding the request to the integration backend. API Gateway has a set of standard response messages that are sent to the client for each type of error. These error responses can be configured on the Rest API. The list of Gateway responses that can be configured can be found here. Learn more about Gateway Responses.
The following code configures a Gateway Response when the response is 'access denied':
RestApi api = new RestApi(this, "books-api"); api.addGatewayResponse("test-response", GatewayResponseOptions.builder() .type(ResponseType.ACCESS_DENIED) .statusCode("500") .responseHeaders(Map.of( "Access-Control-Allow-Origin", "test.com", "test-key", "test-value")) .templates(Map.of( "application/json", "{ \"message\": $context.error.messageString, \"statusCode\": \"488\", \"type\": \"$context.error.responseType\" }")) .build());
OpenAPI Definition
CDK supports creating a REST API by importing an OpenAPI definition file. It currently supports OpenAPI v2.0 and OpenAPI v3.0 definition files. Read more about Configuring a REST API using OpenAPI.
The following code creates a REST API using an external OpenAPI definition JSON file -
Integration integration; SpecRestApi api = SpecRestApi.Builder.create(this, "books-api") .apiDefinition(ApiDefinition.fromAsset("path-to-file.json")) .build(); Resource booksResource = api.root.addResource("books"); booksResource.addMethod("GET", integration);
It is possible to use the addResource()
API to define additional API Gateway Resources.
Note: Deployment will fail if a Resource of the same name is already defined in the Open API specification.
Note: Any default properties configured, such as defaultIntegration
, defaultMethodOptions
, etc. will only be
applied to Resources and Methods defined in the CDK, and not the ones defined in the spec. Use the API Gateway
extensions to OpenAPI
to configure these.
There are a number of limitations in using OpenAPI definitions in API Gateway. Read the Amazon API Gateway important notes for REST APIs for more details.
Note: When starting off with an OpenAPI definition using SpecRestApi
, it is not possible to configure some
properties that can be configured directly in the OpenAPI specification file. This is to prevent people duplication
of these properties and potential confusion.
Endpoint configuration
By default, SpecRestApi
will create an edge optimized endpoint.
This can be modified as shown below:
ApiDefinition apiDefinition; SpecRestApi api = SpecRestApi.Builder.create(this, "ExampleRestApi") .apiDefinition(apiDefinition) .endpointTypes(List.of(EndpointType.PRIVATE)) .build();
Note: For private endpoints you will still need to provide the
x-amazon-apigateway-policy
and
x-amazon-apigateway-endpoint-configuration
in your openApi file.
Metrics
The API Gateway service sends metrics around the performance of Rest APIs to Amazon CloudWatch.
These metrics can be referred to using the metric APIs available on the RestApi
construct.
The APIs with the metric
prefix can be used to get reference to specific metrics for this API. For example,
the method below refers to the client side errors metric for this API.
RestApi api = new RestApi(this, "my-api"); Metric clientErrorMetric = api.metricClientError();
APIGateway v2
APIGateway v2 APIs are now moved to its own package named aws-apigatewayv2
. For backwards compatibility, existing
APIGateway v2 "CFN resources" (such as CfnApi
) that were previously exported as part of this package, are still
exported from here and have been marked deprecated. However, updates to these CloudFormation resources, such as new
properties and new resource types will not be available.
Move to using aws-apigatewayv2
to get the latest APIs and updates.
This module is part of the AWS Cloud Development Kit project. Deprecated: AWS CDK v1 has reached End-of-Support on 2023-06-01. This package is no longer being updated, and users should migrate to AWS CDK v2. For more information on how to migrate, see https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html
-
ClassDescriptionOptions when binding a log destination to a RestApi Stage.A builder for
AccessLogDestinationConfig
An implementation forAccessLogDestinationConfig
$context variables that can be used to customize access log pattern.factory methods for access log format.Options to the UsagePlan.addApiKey() method.A builder forAddApiKeyOptions
An implementation forAddApiKeyOptions
Represents an OpenAPI definition asset.Post-Binding Configuration for a CDK construct.A builder forApiDefinitionConfig
An implementation forApiDefinitionConfig
S3 location of the API definition file.A builder forApiDefinitionS3Location
An implementation forApiDefinitionS3Location
An API Gateway ApiKey.A fluent builder forApiKey
.The options for creating an API Key.A builder forApiKeyOptions
An implementation forApiKeyOptions
ApiKey Properties.A builder forApiKeyProps
An implementation forApiKeyProps
OpenAPI specification from a local file.Example:Base class for all custom authorizers.This type of integration lets an API expose AWS service actions.A fluent builder forAwsIntegration
.Example:A builder forAwsIntegrationProps
An implementation forAwsIntegrationProps
This resource creates a base path that clients who call your API must use in the invocation URL.A fluent builder forBasePathMapping
.Example:A builder forBasePathMappingOptions
An implementation forBasePathMappingOptions
Example:A builder forBasePathMappingProps
An implementation forBasePathMappingProps
A CloudFormationAWS::ApiGateway::Account
.A fluent builder forCfnAccount
.Properties for defining aCfnAccount
.A builder forCfnAccountProps
An implementation forCfnAccountProps
A CloudFormationAWS::ApiGateway::ApiKey
.A fluent builder forCfnApiKey
.StageKey
is a property of the AWS::ApiGateway::ApiKey resource that specifies the stage to associate with the API key.A builder forCfnApiKey.StageKeyProperty
An implementation forCfnApiKey.StageKeyProperty
Properties for defining aCfnApiKey
.A builder forCfnApiKeyProps
An implementation forCfnApiKeyProps
Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.A CloudFormationAWS::ApiGateway::Authorizer
.A fluent builder forCfnAuthorizer
.Properties for defining aCfnAuthorizer
.A builder forCfnAuthorizerProps
An implementation forCfnAuthorizerProps
Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.A CloudFormationAWS::ApiGateway::BasePathMapping
.A fluent builder forCfnBasePathMapping
.Properties for defining aCfnBasePathMapping
.A builder forCfnBasePathMappingProps
An implementation forCfnBasePathMappingProps
A CloudFormationAWS::ApiGateway::ClientCertificate
.A fluent builder forCfnClientCertificate
.Properties for defining aCfnClientCertificate
.A builder forCfnClientCertificateProps
An implementation forCfnClientCertificateProps
A CloudFormationAWS::ApiGateway::Deployment
.TheAccessLogSetting
property type specifies settings for logging access in this stage.A builder forCfnDeployment.AccessLogSettingProperty
An implementation forCfnDeployment.AccessLogSettingProperty
A fluent builder forCfnDeployment
.TheCanarySetting
property type specifies settings for the canary deployment in this stage.A builder forCfnDeployment.CanarySettingProperty
An implementation forCfnDeployment.CanarySettingProperty
TheDeploymentCanarySettings
property type specifies settings for the canary deployment.A builder forCfnDeployment.DeploymentCanarySettingsProperty
An implementation forCfnDeployment.DeploymentCanarySettingsProperty
TheMethodSetting
property type configures settings for all methods in a stage.A builder forCfnDeployment.MethodSettingProperty
An implementation forCfnDeployment.MethodSettingProperty
StageDescription
is a property of the AWS::ApiGateway::Deployment resource that configures a deployment stage.A builder forCfnDeployment.StageDescriptionProperty
An implementation forCfnDeployment.StageDescriptionProperty
Properties for defining aCfnDeployment
.A builder forCfnDeploymentProps
An implementation forCfnDeploymentProps
Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.A CloudFormationAWS::ApiGateway::DocumentationPart
.A fluent builder forCfnDocumentationPart
.TheLocation
property specifies the location of the Amazon API Gateway API entity that the documentation applies to.A builder forCfnDocumentationPart.LocationProperty
An implementation forCfnDocumentationPart.LocationProperty
Properties for defining aCfnDocumentationPart
.A builder forCfnDocumentationPartProps
An implementation forCfnDocumentationPartProps
A CloudFormationAWS::ApiGateway::DocumentationVersion
.A fluent builder forCfnDocumentationVersion
.Properties for defining aCfnDocumentationVersion
.A builder forCfnDocumentationVersionProps
An implementation forCfnDocumentationVersionProps
A CloudFormationAWS::ApiGateway::DomainName
.A fluent builder forCfnDomainName
.TheEndpointConfiguration
property type specifies the endpoint types of an Amazon API Gateway domain name.A builder forCfnDomainName.EndpointConfigurationProperty
An implementation forCfnDomainName.EndpointConfigurationProperty
The mutual TLS authentication configuration for a custom domain name.A builder forCfnDomainName.MutualTlsAuthenticationProperty
An implementation forCfnDomainName.MutualTlsAuthenticationProperty
Properties for defining aCfnDomainName
.A builder forCfnDomainNameProps
An implementation forCfnDomainNameProps
Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.A CloudFormationAWS::ApiGateway::GatewayResponse
.A fluent builder forCfnGatewayResponse
.Properties for defining aCfnGatewayResponse
.A builder forCfnGatewayResponseProps
An implementation forCfnGatewayResponseProps
Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.A CloudFormationAWS::ApiGateway::Method
.A fluent builder forCfnMethod
.Integration
is a property of the AWS::ApiGateway::Method resource that specifies information about the target backend that a method calls.A builder forCfnMethod.IntegrationProperty
An implementation forCfnMethod.IntegrationProperty
IntegrationResponse
is a property of the Amazon API Gateway Method Integration property type that specifies the response that API Gateway sends after a method's backend finishes processing a request.A builder forCfnMethod.IntegrationResponseProperty
An implementation forCfnMethod.IntegrationResponseProperty
Represents a method response of a given HTTP status code returned to the client.A builder forCfnMethod.MethodResponseProperty
An implementation forCfnMethod.MethodResponseProperty
Properties for defining aCfnMethod
.A builder forCfnMethodProps
An implementation forCfnMethodProps
A CloudFormationAWS::ApiGateway::Model
.A fluent builder forCfnModel
.Properties for defining aCfnModel
.A builder forCfnModelProps
An implementation forCfnModelProps
Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.A CloudFormationAWS::ApiGateway::RequestValidator
.A fluent builder forCfnRequestValidator
.Properties for defining aCfnRequestValidator
.A builder forCfnRequestValidatorProps
An implementation forCfnRequestValidatorProps
A CloudFormationAWS::ApiGateway::Resource
.A fluent builder forCfnResource
.Properties for defining aCfnResource
.A builder forCfnResourceProps
An implementation forCfnResourceProps
A CloudFormationAWS::ApiGateway::RestApi
.A fluent builder forCfnRestApi
.TheEndpointConfiguration
property type specifies the endpoint types of a REST API.A builder forCfnRestApi.EndpointConfigurationProperty
An implementation forCfnRestApi.EndpointConfigurationProperty
S3Location
is a property of the AWS::ApiGateway::RestApi resource that specifies the Amazon S3 location of a OpenAPI (formerly Swagger) file that defines a set of RESTful APIs in JSON or YAML.A builder forCfnRestApi.S3LocationProperty
An implementation forCfnRestApi.S3LocationProperty
Properties for defining aCfnRestApi
.A builder forCfnRestApiProps
An implementation forCfnRestApiProps
Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.A CloudFormationAWS::ApiGateway::Stage
.TheAccessLogSetting
property type specifies settings for logging access in this stage.A builder forCfnStage.AccessLogSettingProperty
An implementation forCfnStage.AccessLogSettingProperty
A fluent builder forCfnStage
.Configuration settings of a canary deployment.A builder forCfnStage.CanarySettingProperty
An implementation forCfnStage.CanarySettingProperty
TheMethodSetting
property type configures settings for all methods in a stage.A builder forCfnStage.MethodSettingProperty
An implementation forCfnStage.MethodSettingProperty
Properties for defining aCfnStage
.A builder forCfnStageProps
An implementation forCfnStageProps
Deprecated.moved to package aws-apigatewayv2Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.Deprecated.moved to package aws-apigatewayv2Deprecated.Deprecated.A CloudFormationAWS::ApiGateway::UsagePlan
.API stage name of the associated API stage in a usage plan.A builder forCfnUsagePlan.ApiStageProperty
An implementation forCfnUsagePlan.ApiStageProperty
A fluent builder forCfnUsagePlan
.QuotaSettings
is a property of the AWS::ApiGateway::UsagePlan resource that specifies a target for the maximum number of requests users can make to your REST APIs.A builder forCfnUsagePlan.QuotaSettingsProperty
An implementation forCfnUsagePlan.QuotaSettingsProperty
ThrottleSettings
is a property of the AWS::ApiGateway::UsagePlan resource that specifies the overall request rate (average requests per second) and burst capacity when users call your REST APIs.A builder forCfnUsagePlan.ThrottleSettingsProperty
An implementation forCfnUsagePlan.ThrottleSettingsProperty
A CloudFormationAWS::ApiGateway::UsagePlanKey
.A fluent builder forCfnUsagePlanKey
.Properties for defining aCfnUsagePlanKey
.A builder forCfnUsagePlanKeyProps
An implementation forCfnUsagePlanKeyProps
Properties for defining aCfnUsagePlan
.A builder forCfnUsagePlanProps
An implementation forCfnUsagePlanProps
A CloudFormationAWS::ApiGateway::VpcLink
.A fluent builder forCfnVpcLink
.Properties for defining aCfnVpcLink
.A builder forCfnVpcLinkProps
An implementation forCfnVpcLinkProps
Cognito user pools based custom authorizer.A fluent builder forCognitoUserPoolsAuthorizer
.Properties for CognitoUserPoolsAuthorizer.A builder forCognitoUserPoolsAuthorizerProps
An implementation forCognitoUserPoolsAuthorizerProps
Example:Example:Example:Example:A builder forCorsOptions
An implementation forCorsOptions
A Deployment of a REST API.A fluent builder forDeployment
.Example:A builder forDeploymentProps
An implementation forDeploymentProps
Example:A fluent builder forDomainName
.Example:A builder forDomainNameAttributes
An implementation forDomainNameAttributes
Example:A builder forDomainNameOptions
An implementation forDomainNameOptions
Example:A builder forDomainNameProps
An implementation forDomainNameProps
Deprecated.You should use Model.EMPTY_MODELThe endpoint configuration of a REST API, including VPCs and endpoint types.A builder forEndpointConfiguration
An implementation forEndpointConfiguration
Example:Deprecated.You should use Model.ERROR_MODELConfigure the response received by clients, produced from the API Gateway backend.A fluent builder forGatewayResponse
.Options to add gateway response.A builder forGatewayResponseOptions
An implementation forGatewayResponseOptions
Properties for a new gateway response.A builder forGatewayResponseProps
An implementation forGatewayResponseProps
You can integrate an API method with an HTTP endpoint using the HTTP proxy integration or the HTTP custom integration,.A fluent builder forHttpIntegration
.Example:A builder forHttpIntegrationProps
An implementation forHttpIntegrationProps
Access log destination for a RestApi Stage.Internal default implementation forIAccessLogDestination
.A proxy class which represents a concrete javascript instance of this type.API keys are alphanumeric string values that you distribute to app developer customers to grant access to your API.Internal default implementation forIApiKey
.A proxy class which represents a concrete javascript instance of this type.Represents an API Gateway authorizer.Internal default implementation forIAuthorizer
.A proxy class which represents a concrete javascript instance of this type.Represents an identity source.Internal default implementation forIDomainName
.A proxy class which represents a concrete javascript instance of this type.Represents gateway response resource.Internal default implementation forIGatewayResponse
.A proxy class which represents a concrete javascript instance of this type.Internal default implementation forIModel
.A proxy class which represents a concrete javascript instance of this type.OpenAPI specification from an inline JSON object.Base class for backend integrations for an API Gateway method.A fluent builder forIntegration
.Result of binding an Integration to a Method.A builder forIntegrationConfig
An implementation forIntegrationConfig
Example:A builder forIntegrationOptions
An implementation forIntegrationOptions
Example:A builder forIntegrationProps
An implementation forIntegrationProps
Example:A builder forIntegrationResponse
An implementation forIntegrationResponse
Example:Internal default implementation forIRequestValidator
.A proxy class which represents a concrete javascript instance of this type.Internal default implementation forIResource
.A proxy class which represents a concrete javascript instance of this type.Internal default implementation forIRestApi
.A proxy class which represents a concrete javascript instance of this type.Represents an APIGateway Stage.Internal default implementation forIStage
.A proxy class which represents a concrete javascript instance of this type.A UsagePlan, either managed by this CDK app, or imported.Internal default implementation forIUsagePlan
.A proxy class which represents a concrete javascript instance of this type.Represents an API Gateway VpcLink.Internal default implementation forIVpcLink
.A proxy class which represents a concrete javascript instance of this type.Represents a JSON schema definition of the structure of a REST API model.A builder forJsonSchema
An implementation forJsonSchema
Example:Example:Properties for controlling items output in JSON standard format.A builder forJsonWithStandardFieldProps
An implementation forJsonWithStandardFieldProps
Base properties for all lambda authorizers.A builder forLambdaAuthorizerProps
An implementation forLambdaAuthorizerProps
Integrates an AWS Lambda function to an API Gateway method.A fluent builder forLambdaIntegration
.Example:A builder forLambdaIntegrationOptions
An implementation forLambdaIntegrationOptions
Defines an API Gateway REST API with AWS Lambda proxy integration.A fluent builder forLambdaRestApi
.Example:A builder forLambdaRestApiProps
An implementation forLambdaRestApiProps
Use CloudWatch Logs as a custom access log destination for API Gateway.Example:A fluent builder forMethod
.Example:A builder forMethodDeploymentOptions
An implementation forMethodDeploymentOptions
Example:Example:A builder forMethodOptions
An implementation forMethodOptions
Example:A builder forMethodProps
An implementation forMethodProps
Example:A builder forMethodResponse
An implementation forMethodResponse
This type of integration lets API Gateway return a response without sending the request further to the backend.A fluent builder forMockIntegration
.Example:A fluent builder forModel
.Example:A builder forModelOptions
An implementation forModelOptions
Example:A builder forModelProps
An implementation forModelProps
The mTLS authentication configuration for a custom domain name.A builder forMTLSConfig
An implementation forMTLSConfig
Example:Time period for which quota settings apply.Defines a {proxy+} greedy resource and an ANY method on a route.A fluent builder forProxyResource
.Example:A builder forProxyResourceOptions
An implementation forProxyResourceOptions
Example:A builder forProxyResourceProps
An implementation forProxyResourceProps
Specifies the maximum number of requests that clients can make to API Gateway APIs.A builder forQuotaSettings
An implementation forQuotaSettings
An API Gateway ApiKey, for which a rate limiting configuration can be specified.A fluent builder forRateLimitedApiKey
.RateLimitedApiKey properties.A builder forRateLimitedApiKeyProps
An implementation forRateLimitedApiKeyProps
Request-based lambda authorizer that recognizes the caller's identity via request parameters, such as headers, paths, query strings, stage variables, or context variables.A fluent builder forRequestAuthorizer
.Properties for RequestAuthorizer.A builder forRequestAuthorizerProps
An implementation forRequestAuthorizerProps
Configure what must be included in therequestContext
.A builder forRequestContext
An implementation forRequestContext
Example:A fluent builder forRequestValidator
.Example:A builder forRequestValidatorOptions
An implementation forRequestValidatorOptions
Example:A builder forRequestValidatorProps
An implementation forRequestValidatorProps
Example:A fluent builder forResource
.Attributes that can be specified when importing a Resource.A builder forResourceAttributes
An implementation forResourceAttributes
Example:A builder forResourceOptions
An implementation forResourceOptions
Example:A builder forResourceProps
An implementation forResourceProps
Supported types of gateway responses.Represents a REST API in Amazon API Gateway.A fluent builder forRestApi
.Attributes that can be specified when importing a RestApi.A builder forRestApiAttributes
An implementation forRestApiAttributes
Base implementation that are common to various implementations of IRestApi.Represents the props that all Rest APIs share.A builder forRestApiBaseProps
An implementation forRestApiBaseProps
Deprecated.superseded byRestApiBaseProps
Deprecated.Deprecated.Props to create a new instance of RestApi.A builder forRestApiProps
An implementation forRestApiProps
OpenAPI specification from an S3 archive.The minimum version of the SSL protocol that you want API Gateway to use for HTTPS connections.Represents a REST API in Amazon API Gateway, created with an OpenAPI specification.A fluent builder forSpecRestApi
.Props to instantiate a new SpecRestApi.A builder forSpecRestApiProps
An implementation forSpecRestApiProps
Example:A fluent builder forStage
.Example:A builder forStageOptions
An implementation forStageOptions
Example:A builder forStageProps
An implementation forStageProps
Options when configuring Step Functions synchronous integration with Rest API.A builder forStepFunctionsExecutionIntegrationOptions
An implementation forStepFunctionsExecutionIntegrationOptions
Options to integrate with various StepFunction API.Defines an API Gateway REST API with a Synchrounous Express State Machine as a proxy integration.A fluent builder forStepFunctionsRestApi
.Properties for StepFunctionsRestApi.A builder forStepFunctionsRestApiProps
An implementation forStepFunctionsRestApiProps
Container for defining throttling parameters to API stages or methods.A builder forThrottleSettings
An implementation forThrottleSettings
Represents per-method throttling for a resource.A builder forThrottlingPerMethod
An implementation forThrottlingPerMethod
Token based lambda authorizer that recognizes the caller's identity as a bearer token, such as a JSON Web Token (JWT) or an OAuth token.A fluent builder forTokenAuthorizer
.Properties for TokenAuthorizer.A builder forTokenAuthorizerProps
An implementation forTokenAuthorizerProps
Example:A fluent builder forUsagePlan
.Represents the API stages that a usage plan applies to.A builder forUsagePlanPerApiStage
An implementation forUsagePlanPerApiStage
Example:A builder forUsagePlanProps
An implementation forUsagePlanProps
Define a new VPC Link Specifies an API Gateway VPC link for a RestApi to access resources in an Amazon Virtual Private Cloud (VPC).A fluent builder forVpcLink
.Properties for a VpcLink.A builder forVpcLinkProps
An implementation forVpcLinkProps