aws-cdk.aws-apigatewayv2 1.55.0

The CDK Construct Library for AWS::APIGatewayv2

AWS::APIGatewayv2 Construct Library

---

All classes with the Cfn prefix in this module (CFN Resources) are always stable and safe to use.

The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the Semantic Versioning model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.

---

Table of Contents

• Introduction

• HTTP API

  • Defining HTTP APIs
  • Cross Origin Resource Sharing (CORS)
  • Publishing HTTP APIs
  • Custom Domain

Introduction

Amazon API Gateway is an AWS service for creating, publishing, maintaining, monitoring, and securing REST, HTTP, and WebSocket APIs at any scale. API developers can create APIs that access AWS or other web services, as well as data stored in the AWS Cloud. As an API Gateway API developer, you can create APIs for use in your own client applications. Read the Amazon API Gateway Developer Guide.

This module supports features under API Gateway v2 that lets users set up Websocket and HTTP APIs. REST APIs can be created using the @aws-cdk/aws-apigateway module.

HTTP API

HTTP APIs enable creation of RESTful APIs that integrate with AWS Lambda functions, known as Lambda proxy integration, or to any routable HTTP endpoint, known as HTTP proxy integration.

Defining HTTP APIs

HTTP APIs have two fundamental concepts - Routes and Integrations.

Routes direct incoming API requests to backend resources. Routes consist of two parts: an HTTP method and a resource path, such as, GET /books. Learn more at Working with routes. Use the ANY method to match any methods for a route that are not explicitly defined.

Integrations define how the HTTP API responds when a client reaches a specific Route. HTTP APIs support two types of integrations - Lambda proxy integration and HTTP proxy integration. Learn more at Configuring integrations.

The code snippet below configures a route GET /books with an HTTP proxy integration and uses the ANY method to proxy all other HTTP method calls to /books to a lambda proxy.

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
get_books_integration = HttpProxyIntegration(
    url="https://get-books-proxy.myproxy.internal"
)

books_default_fn = lambda.Function(stack, "BooksDefaultFn", ...)
books_default_integration = LambdaProxyIntegration(
    handler=books_default_fn
)

http_api = HttpApi(stack, "HttpApi")

http_api.add_routes(
    path="/books",
    methods=[HttpMethod.GET],
    integration=get_books_integration
)
http_api.add_routes(
    path="/books",
    methods=[HttpMethod.ANY],
    integration=books_default_integration
)

The defaultIntegration option while defining HTTP APIs lets you create a default catch-all integration that is matched when a client reaches a route that is not explicitly defined.

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
HttpApi(stack, "HttpProxyApi",
    default_integration=HttpProxyIntegration(
        url="http://example.com"
    )
)

Cross Origin Resource Sharing (CORS)

Cross-origin resource sharing (CORS) is a browser security feature that restricts HTTP requests that are initiated from scripts running in the browser. Enabling CORS will allow requests to your API from a web application hosted in a domain different from your API domain.

When configured CORS for an HTTP API, API Gateway automatically sends a response to preflight OPTIONS requests, even if there isn't an OPTIONS route configured. Note that, when this option is used, API Gateway will ignore CORS headers returned from your backend integration. Learn more about Configuring CORS for an HTTP API.

The corsPreflight option lets you specify a CORS configuration for an API.

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
HttpApi(stack, "HttpProxyApi",
    cors_preflight={
        "allow_credentials": True,
        "allow_headers": ["Authorization"],
        "allow_methods": [HttpMethod.GET, HttpMethod.HEAD, HttpMethod.OPTIONS, HttpMethod.POST],
        "allow_origins": ["*"],
        "max_age": Duration.days(10)
    }
)

Publishing HTTP APIs

A Stage is a logical reference to a lifecycle state of your API (for example, dev, prod, beta, or v2). API stages are identified by their stage name. Each stage is a named reference to a deployment of the API made available for client applications to call.

Use HttpStage to create a Stage resource for HTTP APIs. The following code sets up a Stage, whose URL is available at https://{api_id}.execute-api.{region}.amazonaws.com/beta.

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
HttpStage(stack, "Stage",
    http_api=api,
    stage_name="beta"
)

If you omit the stageName will create a $default stage. A $default stage is one that is served from the base of the API's URL - https://{api_id}.execute-api.{region}.amazonaws.com/.

Note that, HttpApi will always creates a $default stage, unless the createDefaultStage property is unset.

Custom Domain

Custom domain names are simpler and more intuitive URLs that you can provide to your API users. Custom domain name are associated to API stages.

The code snippet below creates a custom domain and configures a default domain mapping for your API that maps the custom domain to the $default stage of the API.

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
cert_arn = "arn:aws:acm:us-east-1:111111111111:certificate"
domain_name = "example.com"

dn = DomainName(stack, "DN",
    domain_name=domain_name,
    certificate=acm.Certificate.from_certificate_arn(stack, "cert", cert_arn)
)

api = HttpApi(stack, "HttpProxyProdApi",
    default_integration=LambdaProxyIntegration(handler=handler),
    # https://${dn.domainName}/foo goes to prodApi $default stage
    default_domain_mapping={
        "domain_name": dn,
        "mapping_key": "foo"
    }
)

To associate a specifc Stage to a custom domain mapping -

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
api.add_stage("beta",
    stage_name="beta",
    auto_deploy=True,
    # https://${dn.domainName}/bar goes to the beta stage
    domain_mapping={
        "domain_name": dn,
        "mapping_key": "bar"
    }
)

The same domain name can be associated with stages across different HttpApi as so -

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
api_demo = HttpApi(stack, "DemoApi",
    default_integration=LambdaProxyIntegration(handler=handler),
    # https://${dn.domainName}/demo goes to apiDemo $default stage
    default_domain_mapping={
        "domain_name": dn,
        "mapping_key": "demo"
    }
)

The mappingKey determines the base path of the URL with the custom domain. Each custom domain is only allowed to have one API mapping with undefined mappingKey. If more than one API mappings are specified, mappingKey will be required for all of them. In the sample above, the custom domain is associated with 3 API mapping resources across different APIs and Stages.

API	Stage	URL
api	$default	https://${domainName}/foo
api	beta	https://${domainName}/bar
apiDemo	$default	https://${domainName}/demo