Metadata-Version: 2.1
Name: aws-cdk.aws-apigateway
Version: 1.58.0
Summary: The CDK Construct Library for AWS::ApiGateway
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: ## Amazon API Gateway Construct Library
        
        <!--BEGIN STABILITY BANNER-->---
        
        
        ![cfn-resources: Stable](https://img.shields.io/badge/cfn--resources-stable-success.svg?style=for-the-badge)
        
        ![cdk-constructs: Stable](https://img.shields.io/badge/cdk--constructs-stable-success.svg?style=for-the-badge)
        
        ---
        <!--END STABILITY BANNER-->
        
        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](#defining-apis)
        
          * [Breaking up Methods and Resources across Stacks](#breaking-up-methods-and-resources-across-stacks)
        * [AWS Lambda-backed APIs](#aws-lambda-backed-apis)
        * [Integration Targets](#integration-targets)
        * [Working with models](#working-with-models)
        * [Default Integration and Method Options](#default-integration-and-method-options)
        * [Proxy Routes](#proxy-routes)
        * [Authorizers](#authorizers)
        
          * [IAM-based authorizer](#iam-based-authorizer)
          * [Lambda-based token authorizer](#lambda-based-token-authorizer)
          * [Lambda-based request authorizer](#lambda-based-request-authorizer)
        * [Deployments](#deployments)
        
          * [Deep dive: Invalidation of deployments](#deep-dive-invalidation-of-deployments)
        * [Custom Domains](#custom-domains)
        * [Access Logging](#access-logging)
        * [Cross Origin Resource Sharing (CORS)](#cross-origin-resource-sharing-cors)
        * [Endpoint Configuration](#endpoint-configuration)
        * [Private Integrations](#private-integrations)
        * [Gateway Response](#gateway-response)
        * [OpenAPI Definition](#openapi-definition)
        
          * [Endpoint configuration](#endpoint-configuration)
        * [APIGateway v2](#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}`.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        api = apigateway.RestApi(self, "books-api")
        
        api.root.add_method("ANY")
        
        books = api.root.add_resource("books")
        books.add_method("GET")
        books.add_method("POST")
        
        book = books.add_resource("{book_id}")
        book.add_method("GET")
        book.add_method("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:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        backend = lambda.Function(...)
        apigateway.LambdaRestApi(self, "myapi",
            handler=backend
        )
        ```
        
        You can also supply `proxy: false`, in which case you will have to explicitly
        define the API model:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        backend = lambda.Function(...)
        api = apigateway.LambdaRestApi(self, "myapi",
            handler=backend,
            proxy=False
        )
        
        items = api.root.add_resource("items")
        items.add_method("GET")# GET /items
        items.add_method("POST")# POST /items
        
        item = items.add_resource("{item}")
        item.add_method("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.add_method("DELETE", apigateway.HttpIntegration("http://amazon.com"))
        ```
        
        ### 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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-limits.html) of 200 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:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        from aws_cdk.core import App, CfnOutput, Construct, NestedStack, NestedStackProps, Stack
        from ...lib import Deployment, Method, MockIntegration, PassthroughBehavior, RestApi, 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
        #
        
        class RootStack(Stack):
            def __init__(self, scope):
                super().__init__(scope, "integ-restapi-import-RootStack")
        
                rest_api = RestApi(self, "RestApi",
                    deploy=False
                )
                rest_api.root.add_method("ANY")
        
                pets_stack = PetsStack(self,
                    rest_api_id=rest_api.rest_api_id,
                    root_resource_id=rest_api.rest_api_root_resource_id
                )
                books_stack = BooksStack(self,
                    rest_api_id=rest_api.rest_api_id,
                    root_resource_id=rest_api.rest_api_root_resource_id
                )
                DeployStack(self,
                    rest_api_id=rest_api.rest_api_id,
                    methods=[(SpreadElement ...petsStack.methods
                      pets_stack.methods), (SpreadElement ...booksStack.methods
                      books_stack.methods)]
                )
        
                CfnOutput(self, "PetsURL",
                    value=f"https://{restApi.restApiId}.execute-api.{this.region}.amazonaws.com/prod/pets"
                )
        
                CfnOutput(self, "BooksURL",
                    value=f"https://{restApi.restApiId}.execute-api.{this.region}.amazonaws.com/prod/books"
                )
        
        class PetsStack(NestedStack):
        
            def __init__(self, scope, *, restApiId, rootResourceId, parameters=None, timeout=None, notificationArns=None):
                super().__init__(scope, "integ-restapi-import-PetsStack", restApiId=restApiId, rootResourceId=rootResourceId, parameters=parameters, timeout=timeout, notificationArns=notificationArns)
        
                api = RestApi.from_rest_api_attributes(self, "RestApi",
                    rest_api_id=rest_api_id,
                    root_resource_id=root_resource_id
                )
        
                method = api.root.add_resource("pets").add_method("GET", MockIntegration({
                    "integration_responses": [{
                        "status_code": "200"
                    }],
                    "passthrough_behavior": PassthroughBehavior.NEVER,
                    "request_templates": {
                        "application/json": "{ \"statusCode\": 200 }"
                    }
                }),
                    method_responses=[MethodResponse(status_code="200")]
                )
        
                self.methods.push(method)
        
        class BooksStack(NestedStack):
        
            def __init__(self, scope, *, restApiId, rootResourceId, parameters=None, timeout=None, notificationArns=None):
                super().__init__(scope, "integ-restapi-import-BooksStack", restApiId=restApiId, rootResourceId=rootResourceId, parameters=parameters, timeout=timeout, notificationArns=notificationArns)
        
                api = RestApi.from_rest_api_attributes(self, "RestApi",
                    rest_api_id=rest_api_id,
                    root_resource_id=root_resource_id
                )
        
                method = api.root.add_resource("books").add_method("GET", MockIntegration({
                    "integration_responses": [{
                        "status_code": "200"
                    }],
                    "passthrough_behavior": PassthroughBehavior.NEVER,
                    "request_templates": {
                        "application/json": "{ \"statusCode\": 200 }"
                    }
                }),
                    method_responses=[MethodResponse(status_code="200")]
                )
        
                self.methods.push(method)
        
        class DeployStack(NestedStack):
            def __init__(self, scope, *, restApiId, methods=None, parameters=None, timeout=None, notificationArns=None):
                super().__init__(scope, "integ-restapi-import-DeployStack", restApiId=restApiId, methods=methods, parameters=parameters, timeout=timeout, notificationArns=notificationArns)
        
                deployment = Deployment(self, "Deployment",
                    api=RestApi.from_rest_api_id(self, "RestApi", rest_api_id)
                )
                (methods ?? []).for_each((method) => deployment.node.addDependency(method))
                Stage(self, "Stage", deployment=deployment)
        
        RootStack(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:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        get_book_handler = lambda.Function(...)
        get_book_integration = apigateway.LambdaIntegration(get_book_handler)
        book.add_method("GET", get_book_integration)
        ```
        
        Integration options can be optionally be specified:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        get_book_integration = apigateway.LambdaIntegration(get_book_handler,
            content_handling=apigateway.ContentHandling.CONVERT_TO_TEXT, # convert to base64
            credentials_passthrough=True
        )
        ```
        
        Method options can optionally be specified when adding methods:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        book.add_method("GET", get_book_integration,
            authorization_type=apigateway.AuthorizationType.IAM,
            api_key_required=True
        )
        ```
        
        The following example shows how to use an API Key with a usage plan:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        hello = lambda.Function(self, "hello",
            runtime=lambda.Runtime.NODEJS_10_X,
            handler="hello.handler",
            code=lambda.Code.from_asset("lambda")
        )
        
        api = apigateway.RestApi(self, "hello-api")
        integration = apigateway.LambdaIntegration(hello)
        
        v1 = api.root.add_resource("v1")
        echo = v1.add_resource("echo")
        echo_method = echo.add_method("GET", integration, api_key_required=True)
        key = api.add_api_key("ApiKey")
        
        plan = api.add_usage_plan("UsagePlan",
            name="Easy",
            api_key=key,
            throttle={
                "rate_limit": 10,
                "burst_limit": 2
            }
        )
        
        plan.add_api_stage(
            stage=api.deployment_stage,
            throttle=[{
                "method": echo_method,
                "throttle": {
                    "rate_limit": 10,
                    "burst_limit": 2
                }
            }
            ]
        )
        ```
        
        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.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        key = api.add_api_key("ApiKey",
            api_key_name="myApiKey1",
            value="MyApiKeyThatIsAtLeast20Characters"
        )
        ```
        
        Existing API keys can also be imported into a CDK app using its id.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        imported_key = ApiKey.from_api_key_id(self, "imported-key", "<api-key-id>")
        ```
        
        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 :
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        hello = lambda.Function(self, "hello",
            runtime=lambda.Runtime.NODEJS_10_X,
            handler="hello.handler",
            code=lambda.Code.from_asset("lambda")
        )
        
        api = apigateway.RestApi(self, "hello-api")
        integration = apigateway.LambdaIntegration(hello)
        
        v1 = api.root.add_resource("v1")
        echo = v1.add_resource("echo")
        echo_method = echo.add_method("GET", integration, api_key_required=True)
        
        key = apigateway.RateLimitedApiKey(self, "rate-limited-api-key",
            customer_id="hello-customer",
            resources=[api],
            quota={
                "limit": 10000,
                "period": apigateway.Period.MONTH
            }
        )
        ```
        
        ## 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.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        hello = lambda.Function(self, "hello",
            runtime=lambda.Runtime.NODEJS_10_X,
            handler="hello.handler",
            code=lambda.Code.from_asset("lambda")
        )
        
        api = apigateway.RestApi(self, "hello-api")
        resource = api.root.add_resource("v1")
        ```
        
        You can define more parameters on the integration to tune the behavior of API Gateway
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        integration = LambdaIntegration(hello,
            proxy=False,
            request_parameters={
                # 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"
            },
            allow_test_invoke=True,
            request_templates={
                # 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(action="sayHello", poll_id="$util.escapeJavaScript($input.params('who'))")
            },
            # This parameter defines the behavior of the engine is no suitable response template is found
            passthrough_behavior=PassthroughBehavior.NEVER,
            integration_responses=[{
                # 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
                "status_code": "200",
                "response_templates": {
                    # 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(state="ok", greeting="$util.escapeJavaScript($input.body)")
                },
                "response_parameters": {
                    # 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'"
                }
            }, {
                # For errors, we check if the error message is not empty, get the error data
                "selection_pattern": "(\n|.)+",
                # We will set the response status code to 200
                "status_code": "400",
                "response_templates": {
                    "application/json": JSON.stringify(state="error", message="$util.escapeJavaScript($input.path('$.errorMessage'))")
                },
                "response_parameters": {
                    "method.response.header._content-_type": "'application/json'",
                    "method.response.header._access-_control-_allow-_origin": "'*'",
                    "method.response.header._access-_control-_allow-_credentials": "'true'"
                }
            }
            ]
        )
        ```
        
        You can define models for your responses (and requests)
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        # We define the JSON Schema for the transformed valid response
        response_model = api.add_model("ResponseModel",
            content_type="application/json",
            model_name="ResponseModel",
            schema={
                "schema": JsonSchemaVersion.DRAFT4,
                "title": "pollResponse",
                "type": JsonSchemaType.OBJECT,
                "properties": {
                    "state": {"type": JsonSchemaType.STRING},
                    "greeting": {"type": JsonSchemaType.STRING}
                }
            }
        )
        
        # We define the JSON Schema for the transformed error response
        error_response_model = api.add_model("ErrorResponseModel",
            content_type="application/json",
            model_name="ErrorResponseModel",
            schema={
                "schema": JsonSchemaVersion.DRAFT4,
                "title": "errorResponse",
                "type": JsonSchemaType.OBJECT,
                "properties": {
                    "state": {"type": JsonSchemaType.STRING},
                    "message": {"type": JsonSchemaType.STRING}
                }
            }
        )
        ```
        
        And reference all on your method definition.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        resource.add_method("GET", integration,
            # We can mark the parameters as required
            request_parameters={
                "method.request.querystring.who": True
            },
            # we can set request validator options like below
            request_validator_options={
                "request_validator_name": "test-validator",
                "validate_request_body": True,
                "validate_request_parameters": False
            },
            method_responses=[{
                # Successful response from the integration
                "status_code": "200",
                # Define what parameters are allowed or not
                "response_parameters": {
                    "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
                "response_models": {
                    "application/json": response_model
                }
            }, {
                # Same thing for the error responses
                "status_code": "400",
                "response_parameters": {
                    "method.response.header._content-_type": True,
                    "method.response.header._access-_control-_allow-_origin": True,
                    "method.response.header._access-_control-_allow-_credentials": True
                },
                "response_models": {
                    "application/json": error_response_model
                }
            }
            ]
        )
        ```
        
        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.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        books_backend = apigateway.LambdaIntegration(...)
        api = apigateway.RestApi(self, "books",
            default_integration=books_backend
        )
        
        books = api.root.add_resource("books")
        books.add_method("GET")# integrated with `booksBackend`
        books.add_method("POST")# integrated with `booksBackend`
        
        book = books.add_resource("{book_id}")
        book.add_method("GET")
        ```
        
        A Method can be configured with authorization scopes. Authorization scopes are
        used in conjunction with an [authorizer that uses Amazon Cognito user
        pools](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-integrate-with-cognito.html#apigateway-enable-cognito-user-pool).
        Read more about authorization scopes
        [here](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-method.html#cfn-apigateway-method-authorizationscopes).
        
        Authorization scopes for a Method can be configured using the `authorizationScopes` property as shown below -
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        books.add_method("GET", apigateway.HttpIntegration("http://amazon.com"),
            authorization_type=AuthorizationType.COGNITO,
            authorization_scopes=["Scope1", "Scope2"]
        )
        ```
        
        ## 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:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        proxy = resource.add_proxy(
            default_integration=LambdaIntegration(handler),
        
            # "false" will require explicitly adding methods on the `proxy` resource
            any_method=True
        )
        ```
        
        ## Authorizers
        
        API Gateway [supports several different authorization types](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-control-access-to-api.html)
        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:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        get_books = books.add_method("GET", apigateway.HttpIntegration("http://amazon.com"),
            authorization_type=apigateway.AuthorizationType.IAM
        )
        
        iam_user.attach_inline_policy(iam.Policy(self, "AllowBooks",
            statements=[
                iam.PolicyStatement(
                    actions=["execute-api:Invoke"],
                    effect=iam.Effect.Allow,
                    resources=[get_books.method_arn()]
                )
            ]
        ))
        ```
        
        ### Lambda-based token authorizer
        
        API Gateway also allows [lambda functions to be used as authorizers](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html).
        
        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](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html) 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:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        auth_fn = lambda.Function(self, "booksAuthorizerLambda")
        
        auth = apigateway.TokenAuthorizer(self, "booksAuthorizer",
            handler=auth_fn
        )
        
        books.add_method("GET", apigateway.HttpIntegration("http://amazon.com"),
            authorizer=auth
        )
        ```
        
        You can find a full working example [here](test/authorizers/integ.token-authorizer.ts).
        
        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](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html) 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:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        auth_fn = lambda.Function(self, "booksAuthorizerLambda")
        
        auth = apigateway.RequestAuthorizer(self, "booksAuthorizer",
            handler=auth_fn,
            identity_sources=[IdentitySource.header("Authorization")]
        )
        
        books.add_method("GET", apigateway.HttpIntegration("http://amazon.com"),
            authorizer=auth
        )
        ```
        
        You can find a full working example [here](test/authorizers/integ.request-authorizer.ts).
        
        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.
        
        ## Deployments
        
        By default, the `RestApi` construct will automatically create an API Gateway
        [Deployment](https://docs.aws.amazon.com/apigateway/api-reference/resource/deployment/) and a "prod" [Stage](https://docs.aws.amazon.com/apigateway/api-reference/resource/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 to `false`.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        api = apigateway.RestApi(self, "books",
            deploy_options={
                "logging_level": apigateway.MethodLoggingLevel.INFO,
                "data_trace_enabled": True
            }
        )
        ```
        
        ### 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:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        api = apigw.RestApi(self, "MyDomain",
            domain_name={
                "domain_name": "example.com",
                "certificate": acm_certificate_for_example_com
            }
        )
        ```
        
        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.)
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        import aws_cdk.aws_route53 as route53
        import aws_cdk.aws_route53_targets as targets
        
        route53.ARecord(self, "CustomDomainAliasRecord",
            zone=hosted_zone_for_example_com,
            target=route53.RecordTarget.from_alias(targets.ApiGateway(api))
        )
        ```
        
        You can also define a `DomainName` resource directly in order to customize the default behavior:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        apigw.DomainName(self, "custom-domain",
            domain_name="example.com",
            certificate=acm_certificate_for_example_com,
            endpoint_type=apigw.EndpointType.EDGE, # default is REGIONAL
            security_policy=apigw.SecurityPolicy.TLS_1_2
        )
        ```
        
        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](https://example.com/go-to-api1)
        to the `api1` API and [https://example.com/boom](https://example.com/boom) to the `api2` API.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        domain.add_base_path_mapping(api1, base_path="go-to-api1")
        domain.add_base_path_mapping(api2, base_path="boom")
        ```
        
        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`.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        beta_deploy = Deployment(self, "beta-deployment",
            api=restapi
        )
        beta_stage = Stage(self, "beta-stage",
            deployment=beta_deploy
        )
        domain.add_base_path_mapping(restapi, base_path="api/beta", stage=beta_stage)
        ```
        
        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:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        domain.add_base_path_mapping(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`:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        import aws_cdk.aws_route53 as route53
        import aws_cdk.aws_route53_targets as targets
        
        route53.ARecord(self, "CustomDomainAliasRecord",
            zone=hosted_zone_for_example_com,
            target=route53.RecordTarget.from_alias(targets.ApiGatewayDomain(domain_name))
        )
        ```
        
        ## Access Logging
        
        Access logging creates logs everytime 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](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html#context-variable-reference).
        Read more at [Setting Up CloudWatch API Logging in API
        Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-logging.html)
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        # production stage
        prd_log_group = cwlogs.LogGroup(self, "PrdLogs")
        api = apigateway.RestApi(self, "books",
            deploy_options={
                "access_log_destination": apigateway.LogGroupLogDestination(prd_log_group),
                "access_log_format": apigateway.AccessLogFormat.json_with_standard_fields()
            }
        )
        deployment = apigateway.Deployment(stack, "Deployment", api=api)
        
        # development stage
        dev_log_group = cwlogs.LogGroup(self, "DevLogs")
        apigateway.Stage(self, "dev",
            deployment=deployment,
            access_log_destination=apigateway.LogGroupLogDestination(dev_log_group),
            access_log_format=apigateway.AccessLogFormat.json_with_standard_fields(
                caller=False,
                http_method=True,
                ip=True,
                protocol=True,
                request_time=True,
                resource_path=True,
                response_length=True,
                status=True,
                user=True
            )
        )
        ```
        
        The following code will generate the access log in the [CLF format](https://en.wikipedia.org/wiki/Common_Log_Format).
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        log_group = cwlogs.LogGroup(self, "ApiGatewayAccessLogs")
        api = apigateway.RestApi(self, "books",
            deploy_options={
                "access_log_destination": apigateway.LogGroupLogDestination(log_group),
                "access_log_format": apigateway.AccessLogFormat.clf()
            }
        )
        ```
        
        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.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        log_group = cwlogs.LogGroup(self, "ApiGatewayAccessLogs")
        apigateway.RestApi(self, "books",
            deploy_options={
                "access_log_destination": apigateway.LogGroupLogDestination(log_group),
                "access_log_format": apigateway.AccessLogFormat.custom(f"{AccessLogFormat.contextRequestId()} {AccessLogField.contextErrorMessage()} {AccessLogField.contextErrorMessageString()}")
            }
        )
        ```
        
        You can use the `methodOptions` property to configure
        [default method throttling](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-request-throttling.html#apigateway-api-level-throttling-in-usage-plan)
        for a stage. The following snippet configures the a stage that accepts
        100 requests per minute, allowing burst up to 200 requests per minute.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        api = apigateway.RestApi(self, "books")
        deployment = apigateway.Deployment(self, "my-deployment", api=api)
        stage = apigateway.Stage(self, "my-stage",
            deployment=deployment,
            method_options={
                "/*/*": {# This special path applies to all resource paths and all HTTP methods
                    "throttling_rate_limit": 100,
                    "throttling_burst_limit": 200}
            }
        )
        ```
        
        Configuring `methodOptions` on the `deployOptions` of `RestApi` will set the
        throttling behaviors on the default stage that is automatically created.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        api = apigateway.RestApi(self, "books",
            deploy_options={
                "method_options": {
                    "/*/*": {# This special path applies to all resource paths and all HTTP methods
                        "throttling_rate_limit": 100,
                        "throttling_burst_limit": 1000}
                }
            }
        )
        ```
        
        ## Cross Origin Resource Sharing (CORS)
        
        [Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/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](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Preflighted_requests) 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:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        apigateway.RestApi(self, "api",
            default_cors_preflight_options={
                "allow_origins": apigateway.Cors.ALL_ORIGINS,
                "allow_methods": apigateway.Cors.ALL_METHODS
            }
        )
        ```
        
        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.](https://amazon.com.)
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        my_resource.add_cors_preflight(
            allow_origins=["https://amazon.com"],
            allow_methods=["GET", "PUT"]
        )
        ```
        
        See the
        [`CorsOptions`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-apigateway.CorsOptions.html)
        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:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        subtree = resource.add_resource("subtree",
            default_cors_preflight_options={
                "allow_origins": ["https://amazon.com"]
            }
        )
        ```
        
        This means that all resources under `subtree` (inclusive) will have a preflight
        OPTIONS added to them.
        
        See [#906](https://github.com/aws/aws-cdk/issues/906) for a list of CORS
        features which are not yet supported.
        
        ## Endpoint Configuration
        
        API gateway allows you to specify an
        [API Endpoint Type](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-endpoint-types.html).
        To define an endpoint type for the API gateway, use `endpointConfiguration` property:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        api = apigw.RestApi(stack, "api",
            endpoint_configuration={
                "types": [apigw.EndpointType.EDGE]
            }
        )
        ```
        
        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](https://docs.aws.amazon.com/apigateway/latest/developerguide/associate-private-api-with-vpc-endpoint.html).
        
        Here is an example:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        some_endpoint = # Get or Create endpoint here
        api = apigw.RestApi(stack, "api",
            endpoint_configuration={
                "types": [apigw.EndpointType.PRIVATE],
                "vpc_endpoints": [some_endpoint]
            }
        )
        ```
        
        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 -
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        vpc = ec2.Vpc(stack, "VPC")
        nlb = elbv2.NetworkLoadBalancer(stack, "NLB",
            vpc=vpc
        )
        link = apigw.VpcLink(stack, "link",
            targets=[nlb]
        )
        
        integration = apigw.Integration(
            type=apigw.IntegrationType.HTTP_PROXY,
            options={
                "connection_type": apigw.ConnectionType.VPC_LINK,
                "vpc_link": link
            }
        )
        ```
        
        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
        stack = Stack(app, "my-stack")
        
        awesome_link = VpcLink.from_vpc_link_id(stack, "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](https://docs.aws.amazon.com/apigateway/latest/developerguide/supported-gateway-response-types.html).
        Learn more about [Gateway
        Responses](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-gatewayResponse-definition.html).
        
        The following code configures a Gateway Response when the response is 'access denied':
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        api = apigateway.RestApi(self, "books-api")
        api.add_gateway_response("test-response",
            type=ResponseType.ACCESS_DENIED,
            status_code="500",
            response_headers={
                "Access-Control-Allow-Origin": "test.com",
                "test-key": "test-value"
            },
            templates={
                "application/json": "{ \"message\": $context.error.messageString, \"statusCode\": \"488\", \"type\": \"$context.error.responseType\" }"
            }
        )
        ```
        
        ## 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](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-import-api.html).
        
        The following code creates a REST API using an external OpenAPI definition JSON file -
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        api = apigateway.SpecRestApi(self, "books-api",
            api_definition=apigateway.ApiDefinition.from_asset("path-to-file.json")
        )
        
        books_resource = api.root.add_resource("books")
        books_resource.add_method("GET", ...)
        ```
        
        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](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html)
        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](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-known-issues.html#api-gateway-known-issues-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:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        api = apigateway.SpecRestApi(self, "ExampleRestApi",
            # ...
            endpoint_types=[apigateway.EndpointType.PRIVATE]
        )
        ```
        
        **Note:** For private endpoints you will still need to provide the
        [`x-amazon-apigateway-policy`](https://docs.aws.amazon.com/apigateway/latest/developerguide/openapi-extensions-policy.html) and
        [`x-amazon-apigateway-endpoint-configuration`](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-endpoint-configuration.html)
        in your openApi file.
        
        ## 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](https://github.com/aws/aws-cdk) project.
        
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: Typing :: Typed
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved
Requires-Python: >=3.6
Description-Content-Type: text/markdown
