Metadata-Version: 2.1
Name: aws-cdk.aws-apigatewayv2
Version: 1.117.0
Summary: The CDK Construct Library for AWS::APIGatewayv2
Home-page: https://github.com/aws/aws-cdk
Author: Amazon Web Services
License: Apache-2.0
Project-URL: Source, https://github.com/aws/aws-cdk.git
Description: # AWS::APIGatewayv2 Construct Library
        
        <!--BEGIN STABILITY BANNER-->---
        
        
        Features                                   | Stability
        -------------------------------------------|--------------------------------------------------------
        CFN Resources                              | ![Stable](https://img.shields.io/badge/stable-success.svg?style=for-the-badge)
        Higher level constructs for HTTP APIs      | ![Experimental](https://img.shields.io/badge/experimental-important.svg?style=for-the-badge)
        Higher level constructs for Websocket APIs | ![Experimental](https://img.shields.io/badge/experimental-important.svg?style=for-the-badge)
        
        > **CFN Resources:** All classes with the `Cfn` prefix in this module ([CFN Resources](https://docs.aws.amazon.com/cdk/latest/guide/constructs.html#constructs_lib)) are always
        > stable and safe to use.
        
        <!-- -->
        
        > **Experimental:** Higher level constructs in this module that are marked as experimental are
        > 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](https://semver.org/) 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.
        
        ---
        <!--END STABILITY BANNER-->
        
        ## Table of Contents
        
        * [Introduction](#introduction)
        * [HTTP API](#http-api)
        
          * [Defining HTTP APIs](#defining-http-apis)
          * [Cross Origin Resource Sharing (CORS)](#cross-origin-resource-sharing-cors)
          * [Publishing HTTP APIs](#publishing-http-apis)
          * [Custom Domain](#custom-domain)
          * [Managing access](#managing-access)
          * [Metrics](#metrics)
          * [VPC Link](#vpc-link)
          * [Private Integration](#private-integration)
        * [WebSocket API](#websocket-api)
        
        ## 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](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html).
        
        This module supports features under [API Gateway v2](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/AWS_ApiGatewayV2.html)
        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](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-routes.html). 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 Lambda proxy
        integration, HTTP proxy integration and, AWS service integrations, also known as private integrations. Learn more at
        [Configuring integrations](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations.html).
        
        Integrations are available at the `aws-apigatewayv2-integrations` module and more information is available in that module.
        As an early example, the following code snippet configures a route `GET /books` with an HTTP proxy integration all
        configures all other HTTP method calls to `/books` to a lambda proxy.
        
        ```python
        # 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 URL to the endpoint can be retrieved via the `apiEndpoint` attribute. By default this URL is enabled for clients. Use `disableExecuteApiEndpoint` to disable it.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        http_api = HttpApi(stack, "HttpApi",
            disable_execute_api_endpoint=True
        )
        ```
        
        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.
        
        ```python
        # 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)](https://developer.mozilla.org/en-US/docs/Web/HTTP/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](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-cors.html).
        
        The `corsPreflight` option lets you specify a CORS configuration for an API.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        HttpApi(stack, "HttpProxyApi",
            cors_preflight={
                "allow_headers": ["Authorization"],
                "allow_methods": [CorsHttpMethod.GET, CorsHttpMethod.HEAD, CorsHttpMethod.OPTIONS, CorsHttpMethod.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`.
        
        ```python
        # 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.
        
        ```python
        # 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 specific `Stage` to a custom domain mapping -
        
        ```python
        # 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 -
        
        ```python
        # 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`  |
        
        ### Managing access
        
        API Gateway supports multiple mechanisms for [controlling and managing access to your HTTP
        API](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-access-control.html) through authorizers.
        
        These authorizers can be found in the [APIGatewayV2-Authorizers](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-apigatewayv2-authorizers-readme.html) constructs library.
        
        ### Metrics
        
        The API Gateway v2 service sends metrics around the performance of HTTP APIs to Amazon CloudWatch.
        These metrics can be referred to using the metric APIs available on the `HttpApi` 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.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        api = apigw.HttpApi(stack, "my-api")
        client_error_metric = api.metric_client_error()
        ```
        
        Please note that this will return a metric for all the stages defined in the api. It is also possible to refer to metrics for a specific Stage using
        the `metric` methods from the `Stage` construct.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        api = apigw.HttpApi(stack, "my-api")
        stage = HttpStage(stack, "Stage",
            http_api=api
        )
        client_error_metric = stage.metric_client_error()
        ```
        
        ### VPC Link
        
        Private integrations let HTTP APIs connect with AWS resources that are placed behind a VPC. These are usually Application
        Load Balancers, Network Load Balancers or a Cloud Map service. The `VpcLink` construct enables this integration.
        The following code creates a `VpcLink` to a private VPC.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        vpc = ec2.Vpc(stack, "VPC")
        vpc_link = VpcLink(stack, "VpcLink", vpc=vpc)
        ```
        
        Any existing `VpcLink` resource can be imported into the CDK app via the `VpcLink.fromVpcLinkId()`.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        awesome_link = VpcLink.from_vpc_link_id(stack, "awesome-vpc-link", "us-east-1_oiuR12Abd")
        ```
        
        ### Private Integration
        
        Private integrations enable integrating an HTTP API route with private resources in a VPC, such as Application Load Balancers or
        Amazon ECS container-based applications.  Using private integrations, resources in a VPC can be exposed for access by
        clients outside of the VPC.
        
        These integrations can be found in the [APIGatewayV2-Integrations](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-apigatewayv2-integrations-readme.html) constructs library.
        
        ## WebSocket API
        
        A WebSocket API in API Gateway is a collection of WebSocket routes that are integrated with backend HTTP endpoints,
        Lambda functions, or other AWS services. You can use API Gateway features to help you with all aspects of the API
        lifecycle, from creation through monitoring your production APIs. [Read more](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-overview.html)
        
        WebSocket APIs have two fundamental concepts - Routes and Integrations.
        
        WebSocket APIs direct JSON messages to backend integrations based on configured routes. (Non-JSON messages are directed
        to the configured `$default` route.)
        
        Integrations define how the WebSocket API behaves when a client reaches a specific Route. Learn more at
        [Configuring integrations](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-integration-requests.html).
        
        Integrations are available in the `aws-apigatewayv2-integrations` module and more information is available in that module.
        
        To add the default WebSocket routes supported by API Gateway (`$connect`, `$disconnect` and `$default`), configure them as part of api props:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        web_socket_api = WebSocketApi(stack, "mywsapi",
            connect_route_options={"integration": LambdaWebSocketIntegration(handler=connect_handler)},
            disconnect_route_options={"integration": LambdaWebSocketIntegration(handler=disconnet_handler)},
            default_route_options={"integration": LambdaWebSocketIntegration(handler=default_handler)}
        )
        
        WebSocketStage(stack, "mystage",
            web_socket_api=web_socket_api,
            stage_name="dev",
            auto_deploy=True
        )
        ```
        
        To retrieve a websocket URL and a callback URL:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        web_socket_uRL = web_socket_stage.url
        # wss://${this.api.apiId}.execute-api.${s.region}.${s.urlSuffix}/${urlPath}
        callback_uRL = web_socket_uRL.callback_url
        ```
        
        To add any other route:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        web_socket_api = WebSocketApi(stack, "mywsapi")
        web_socket_api.add_route("sendmessage",
            integration=LambdaWebSocketIntegration(
                handler=message_handler
            )
        )
        ```
        
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Typing :: Typed
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved
Classifier: Framework :: AWS CDK
Classifier: Framework :: AWS CDK :: 1
Requires-Python: >=3.6
Description-Content-Type: text/markdown
