API Gateway HTTP and WebSocket API examples using Amazon CLI - Amazon Command Line Interface
Actions
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

API Gateway HTTP and WebSocket API examples using Amazon CLI

The following code examples show you how to perform actions and implement common scenarios by using the Amazon Command Line Interface with API Gateway HTTP and WebSocket API.

Actions are code excerpts from larger programs and must be run in context. While actions show you how to call individual service functions, you can see actions in context in their related scenarios and cross-service examples.

Scenarios are code examples that show you how to accomplish a specific task by calling multiple functions within the same service.

Each example includes a link to GitHub, where you can find instructions on how to set up and run the code in context.

Topics

Actions

The following code example shows how to use create-api-mapping.

Amazon CLI

To create an API mapping for an API

The following create-api-mapping example maps the test stage of an API to the /myApi path of the regional.example.com custom domain name.

aws apigatewayv2 create-api-mapping \
    --domain-name regional.example.com \
    --api-mapping-key myApi \
    --api-id a1b2c3d4 \
    --stage test

Output:

{
    "ApiId": "a1b2c3d4",
    "ApiMappingId": "0qzs2sy7bh",
    "ApiMappingKey": "myApi"
    "Stage": "test"
}

For more information, see Setting up a regional custom domain name in API Gateway in the Amazon API Gateway Developer Guide.

The following code example shows how to use create-api.

Amazon CLI

To create an HTTP API

The following create-api example creates an HTTP API by using quick create. You can use quick create to create an API with an Amazon Lambda or HTTP integration, a default catch-all route, and a default stage that is configured to automatically deploy changes. The following command uses quick create to create an HTTP API that integrates with a Lambda function.

aws apigatewayv2 create-api \
    --name my-http-api \
    --protocol-type HTTP \
    --target arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function

Output:

{
    "ApiEndpoint": "https://a1b2c3d4.execute-api.us-west-2.amazonaws.com",
    "ApiId": "a1b2c3d4",
    "ApiKeySelectionExpression": "$request.header.x-api-key",
    "CreatedDate": "2020-04-08T19:05:45+00:00",
    "Name": "my-http-api",
    "ProtocolType": "HTTP",
    "RouteSelectionExpression": "$request.method $request.path"
}

For more information, see Developing an HTTP API in API Gateway in the Amazon API Gateway Developer Guide.

To create a WebSocket API

The following create-api example creates a WebSocket API with the specified name.

aws apigatewayv2 create-api \
    --name "myWebSocketApi" \
    --protocol-type WEBSOCKET \
    --route-selection-expression '$request.body.action'

Output:

{
    "ApiKeySelectionExpression": "$request.header.x-api-key",
    "Name": "myWebSocketApi",
    "CreatedDate": "2018-11-15T06:23:51Z",
    "ProtocolType": "WEBSOCKET",
    "RouteSelectionExpression": "'$request.body.action'",
    "ApiId": "aabbccddee"
}

For more information, see Create a WebSocket API in API Gateway in the Amazon API Gateway Developer Guide.

  • For API details, see CreateApi in Amazon CLI Command Reference.

The following code example shows how to use create-authorizer.

Amazon CLI

To create a JWT authorizer for an HTTP API

The following create-authorizer example creates a JWT authorizer that uses Amazon Cognito as an identity provider.

aws apigatewayv2 create-authorizer \
    --name my-jwt-authorizer \
    --api-id a1b2c3d4 \
    --authorizer-type JWT \
    --identity-source '$request.header.Authorization' \
    --jwt-configuration Audience=123456abc,Issuer=https://cognito-idp.us-west-2.amazonaws.com/us-west-2_abc123

Output:

{
    "AuthorizerId": "a1b2c3",
    "AuthorizerType": "JWT",
    "IdentitySource": [
        "$request.header.Authorization"
    ],
    "JwtConfiguration": {
        "Audience": [
            "123456abc"
        ],
        "Issuer": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_abc123"
    },
    "Name": "my-jwt-authorizer"
}

For more information, see Controlling access to HTTP APIs with JWT authorizers in the Amazon API Gateway Developer Guide.

The following code example shows how to use create-deployment.

Amazon CLI

To create a deployment for an API

The following create-deployment example creates a deployment for an API and associates that deployment with the dev stage of the API.

aws apigatewayv2 create-deployment \
    --api-id a1b2c3d4 \
    --stage-name dev

Output:

{
    "AutoDeployed": false,
    "CreatedDate": "2020-04-06T23:38:08Z",
    "DeploymentId": "53lz9l",
    "DeploymentStatus": "DEPLOYED"
}

For more information, see API deployment in the Amazon API Gateway Developer Guide.

The following code example shows how to use create-domain-name.

Amazon CLI

To create a custom domain name

The following create-domain-name example creates a regional custom domain name for an API.

aws apigatewayv2 create-domain-name \
    --domain-name regional.example.com \
    --domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678

Output:

{
    "ApiMappingSelectionExpression": "$request.basepath",
    "DomainName": "regional.example.com",
    "DomainNameConfigurations": [
        {
            "ApiGatewayDomainName": "d-id.execute-api.us-west-2.amazonaws.com",
            "CertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678",
            "EndpointType": "REGIONAL",
            "HostedZoneId": "123456789111",
            "SecurityPolicy": "TLS_1_2",
            "DomainNameStatus": "AVAILABLE"
        }
    ]
}

For more information, see Setting up a regional custom domain name in API Gateway in the Amazon API Gateway Developer Guide.

The following code example shows how to use create-integration.

Amazon CLI

To create a WebSocket API integration

The following create-integration example creates a mock integration for a WebSocket API.

aws apigatewayv2 create-integration \
    --api-id aabbccddee \
    --passthrough-behavior WHEN_NO_MATCH \
    --timeout-in-millis 29000 \
    --connection-type INTERNET \
    --integration-type MOCK

Output:

{
    "ConnectionType": "INTERNET",
    "IntegrationId": "0abcdef",
    "IntegrationResponseSelectionExpression": "${integration.response.statuscode}",
    "IntegrationType": "MOCK",
    "PassthroughBehavior": "WHEN_NO_MATCH",
    "PayloadFormatVersion": "1.0",
    "TimeoutInMillis": 29000
}

For more information, see Set up a WebSocket API integration request in API Gateway in the Amazon API Gateway Developer Guide.

To create an HTTP API integration

The following create-integration example creates an Amazon Lambda integration for an HTTP API.

aws apigatewayv2 create-integration \
    --api-id a1b2c3d4 \
    --integration-type AWS_PROXY \
    --integration-uri arn:aws:lambda:us-west-2:123456789012:function:my-function \
    --payload-format-version 2.0

Output:

{
    "ConnectionType": "INTERNET",
    "IntegrationId": "0abcdef",
    "IntegrationMethod": "POST",
    "IntegrationType": "AWS_PROXY",
    "IntegrationUri": "arn:aws:lambda:us-west-2:123456789012:function:my-function",
    "PayloadFormatVersion": "2.0",
    "TimeoutInMillis": 30000
}

For more information, see Configuring integrations for HTTP APIs in the Amazon API Gateway Developer Guide.

The following code example shows how to use create-route.

Amazon CLI

To create a $default route for a WebSocket or HTTP API

The following create-route example creates a $default route for a WebSocket or HTTP API.

aws apigatewayv2 create-route \
    --api-id aabbccddee \
    --route-key '$default'

Output:

{
    "ApiKeyRequired": false,
    "AuthorizationType": "NONE",
    "RouteKey": "$default",
    "RouteId": "1122334"
}

For more information, see Working with routes for WebSocket APIs in the Amazon API Gateway Developer Guide

To create a route for an HTTP API

The following create-route example creates a route named signup that accepts POST requests.

aws apigatewayv2 create-route \
    --api-id aabbccddee \
    --route-key 'POST /signup'

Output:

{
    "ApiKeyRequired": false,
    "AuthorizationType": "NONE",
    "RouteKey": "POST /signup",
    "RouteId": "1122334"
}

For more information, see Working with routes for HTTP APIs in the Amazon API Gateway Developer Guide

  • For API details, see CreateRoute in Amazon CLI Command Reference.

The following code example shows how to use create-stage.

Amazon CLI

To create a stage

The following create-stage example creates a stage named dev for an API.

aws apigatewayv2 create-stage \
    --api-id a1b2c3d4 \
    --stage-name dev

Output:

{
    "CreatedDate": "2020-04-06T23:23:46Z",
    "DefaultRouteSettings": {
        "DetailedMetricsEnabled": false
    },
    "LastUpdatedDate": "2020-04-06T23:23:46Z",
    "RouteSettings": {},
    "StageName": "dev",
    "StageVariables": {},
    "Tags": {}
}

For more information, see Working with stages for HTTP APIs in the Amazon API Gateway Developer Guide.

  • For API details, see CreateStage in Amazon CLI Command Reference.

The following code example shows how to use create-vpc-link.

Amazon CLI

To create a VPC link for an HTTP API

The following create-vpc-link example creates a VPC link for HTTP APIs.

aws apigatewayv2 create-vpc-link \
    --name MyVpcLink \
    --subnet-ids subnet-aaaa subnet-bbbb \
    --security-group-ids sg1234 sg5678

Output:

{
    "CreatedDate": "2020-04-07T00:11:46Z",
    "Name": "MyVpcLink",
    "SecurityGroupIds": [
        "sg1234",
        "sg5678"
    ],
    "SubnetIds": [
        "subnet-aaaa",
        "subnet-bbbb"
    ],
    "Tags": {},
    "VpcLinkId": "abcd123",
    "VpcLinkStatus": "PENDING",
    "VpcLinkStatusMessage": "VPC link is provisioning ENIs",
    "VpcLinkVersion": "V2"
}

For more information, see Working with VPC links for HTTP APIs in the Amazon API Gateway Developer Guide.

  • For API details, see CreateVpcLink in Amazon CLI Command Reference.

The following code example shows how to use delete-access-log-settings.

Amazon CLI

To disable access logging for an API

The following delete-access-log-settings example deletes the access log settings for the $default stage of an API. To disable access logging for a stage, delete its access log settings.

aws apigatewayv2 delete-access-log-settings \
    --api-id a1b2c3d4 \
    --stage-name '$default'

This command produces no output.

For more information, see Configuring logging for an HTTP API in the Amazon API Gateway Developer Guide.

The following code example shows how to use delete-api-mapping.

Amazon CLI

To delete an API mapping

The following delete-api-mapping example deletes an API mapping for the api.example.com custom domain name.

aws apigatewayv2 delete-api-mapping \
    --api-mapping-id a1b2c3 \
    --domain-name api.example.com

This command produces no output.

For more information, see Setting up a regional custom domain name in API Gateway in the Amazon API Gateway Developer Guide.

The following code example shows how to use delete-api.

Amazon CLI

To delete an API

The following delete-api example deletes an API.

aws apigatewayv2 delete-api \
    --api-id a1b2c3d4

This command produces no output.

For more information, see Working with HTTP APIs and Working with WebSocket APIs in the Amazon API Gateway Developer Guide.

  • For API details, see DeleteApi in Amazon CLI Command Reference.

The following code example shows how to use delete-authorizer.

Amazon CLI

To delete an authorizer

The following delete-authorizer example deletes an authorizer.

aws apigatewayv2 delete-authorizer \
    --api-id a1b2c3d4 \
    --authorizer-id a1b2c3

This command produces no output.

For more information, see Controlling access to HTTP APIs with JWT authorizers in the Amazon API Gateway Developer Guide.

The following code example shows how to use delete-cors-configuration.

Amazon CLI

To delete the CORS configuration for an HTTP API

The following delete-cors-configuration example disables CORS for an HTTP API by deleting its CORS configuration.

aws apigatewayv2 delete-cors-configuration \
    --api-id a1b2c3d4

This command produces no output.

For more information, see Configuring CORS for an HTTP API in the Amazon API Gateway Developer Guide.

The following code example shows how to use delete-deployment.

Amazon CLI

To delete a deployment

The following delete-deployment example deletes a deployment of an API.

aws apigatewayv2 delete-deployment \
    --api-id a1b2c3d4 \
    --deployment-id a1b2c3

This command produces no output.

For more information, see API deployment in the Amazon API Gateway Developer Guide.

The following code example shows how to use delete-domain-name.

Amazon CLI

To delete a custom domain name

The following delete-domain-name example deletes a custom domain name.

aws apigatewayv2 delete-domain-name \
    --domain-name api.example.com

This command produces no output.

For more information, see Setting up a regional custom domain name in API Gateway in the Amazon API Gateway Developer Guide.

The following code example shows how to use delete-integration.

Amazon CLI

To delete an integration

The following delete-integration example deletes an API integration.

aws apigatewayv2 delete-integration \
    --api-id a1b2c3d4 \
    --integration-id a1b2c3

This command produces no output.

For more information, see Configuring integrations for HTTP APIs and Setting up WebSocket API integrations in the Amazon API Gateway Developer Guide.

The following code example shows how to use delete-route-settings.

Amazon CLI

To delete route settings

The following delete-route-settings example deletes the route settings for the specified route.

aws apigatewayv2 delete-route-settings \
    --api-id a1b2c3d4 \
    --stage-name dev \
    --route-key 'GET /pets'

This command produces no output.

For more information, see Working with routes for HTTP APIs in the Amazon API Gateway Developer Guide.

The following code example shows how to use delete-route.

Amazon CLI

To delete a route

The following delete-route example deletes an API route.

aws apigatewayv2 delete-route \
    --api-id a1b2c3d4 \
    --route-id a1b2c3

This command produces no output.

For more information, see Working with routes for HTTP APIs in the Amazon API Gateway Developer Guide.

  • For API details, see DeleteRoute in Amazon CLI Command Reference.

The following code example shows how to use delete-stage.

Amazon CLI

To delete a stage

The following delete-stage example deletes the test stage of an API.

aws apigatewayv2 delete-stage \
    --api-id a1b2c3d4 \
    --stage-name test

This command produces no output.

For more information, see Working with stages for HTTP APIs in the Amazon API Gateway Developer Guide.

  • For API details, see DeleteStage in Amazon CLI Command Reference.

The following code example shows how to use delete-vpc-link.

Amazon CLI

To delete a VPC link for an HTTP API

The following delete-vpc-link example deletes a VPC link.

aws apigatewayv2 delete-vpc-link \
    --vpc-link-id abcd123

This command produces no output.

For more information, see Working with VPC links for HTTP APIs in the Amazon API Gateway Developer Guide.

  • For API details, see DeleteVpcLink in Amazon CLI Command Reference.

The following code example shows how to use export-api.

Amazon CLI

To export an OpenAPI definition of an HTTP API

The following export-api example exports an OpenAPI 3.0 definition of an API stage named prod to a YAML file named stage-definition.yaml. The exported definition file includes API Gateway extensions by default.

aws apigatewayv2 export-api \
    --api-id a1b2c3d4 \
    --output-type YAML \
    --specification OAS30 \
    --stage-name prod \
    stage-definition.yaml

This command produces no output.

For more information, see Exporting an HTTP API from API Gateway in the Amazon API Gateway Developer Guide.

  • For API details, see ExportApi in Amazon CLI Command Reference.

The following code example shows how to use get-api-mapping.

Amazon CLI

To get information about an API mapping for a custom domain name

The following get-api-mapping example displays infomation about an API mapping for the api.example.com custom domain name.

aws apigatewayv2 get-api-mapping \
    --api-mapping-id a1b2c3 \
    --domain-name api.example.com

Output:

{
    "ApiId": "a1b2c3d4",
    "ApiMappingId": "a1b2c3d5",
    "ApiMappingKey": "myTestApi"
    "Stage": "test"
}

For more information, see Setting up a regional custom domain name in API Gateway in the Amazon API Gateway Developer Guide.

  • For API details, see GetApiMapping in Amazon CLI Command Reference.

The following code example shows how to use get-api-mappings.

Amazon CLI

To get API mappings for a custom domain name

The following get-api-mappings example displays a list of all of the API mappings for the api.example.com custom domain name.

aws apigatewayv2 get-api-mappings \
    --domain-name api.example.com

Output:

{
    "Items": [
        {
            "ApiId": "a1b2c3d4",
            "ApiMappingId": "a1b2c3d5",
            "ApiMappingKey": "myTestApi"
            "Stage": "test"
        },
        {
            "ApiId": "a5b6c7d8",
            "ApiMappingId": "a1b2c3d6",
            "ApiMappingKey": "myDevApi"
            "Stage": "dev"
        },
    ]
}

For more information, see Setting up a regional custom domain name in API Gateway in the Amazon API Gateway Developer Guide.

  • For API details, see GetApiMappings in Amazon CLI Command Reference.

The following code example shows how to use get-api.

Amazon CLI

To retrieve information about an API

The following get-api example displays information about an API.

aws apigatewayv2 get-api \
    --api-id a1b2c3d4

Output:

{
    "ApiEndpoint": "https://a1b2c3d4.execute-api.us-west-2.amazonaws.com",
    "ApiId": "a1b2c3d4",
    "ApiKeySelectionExpression": "$request.header.x-api-key",
    "CreatedDate": "2020-03-28T00:32:37Z",
    "Name": "my-api",
    "ProtocolType": "HTTP",
    "RouteSelectionExpression": "$request.method $request.path",
    "Tags": {
        "department": "finance"
    }
}

  • For API details, see GetApi in Amazon CLI Command Reference.

The following code example shows how to use get-apis.

Amazon CLI

To retrieve a list of APIs

The following get-apis example lists all of the APIs for the current user.

aws apigatewayv2 get-apis

Output:

{
    "Items": [
        {
            "ApiEndpoint": "wss://a1b2c3d4.execute-api.us-west-2.amazonaws.com",
            "ApiId": "a1b2c3d4",
            "ApiKeySelectionExpression": "$request.header.x-api-key",
            "CreatedDate": "2020-04-07T20:21:59Z",
            "Name": "my-websocket-api",
            "ProtocolType": "WEBSOCKET",
            "RouteSelectionExpression": "$request.body.message",
            "Tags": {}
        },
        {
            "ApiEndpoint": "https://a1b2c3d5.execute-api.us-west-2.amazonaws.com",
            "ApiId": "a1b2c3d5",
            "ApiKeySelectionExpression": "$request.header.x-api-key",
            "CreatedDate": "2020-04-07T20:23:50Z",
            "Name": "my-http-api",
            "ProtocolType": "HTTP",
            "RouteSelectionExpression": "$request.method $request.path",
            "Tags": {}
        }
    ]
}

For more information, see Working with HTTP APIs and Working with WebSocket APIs in the Amazon API Gateway Developer Guide.

  • For API details, see GetApis in Amazon CLI Command Reference.

The following code example shows how to use get-authorizer.

Amazon CLI

To retrieve information about an authorizer

The following get-authorizer example displays information about an authorizer.

aws apigatewayv2 get-authorizer \
    --api-id a1b2c3d4 \
    --authorizer-id a1b2c3

Output:

{
    "AuthorizerId": "a1b2c3",
    "AuthorizerType": "JWT",
    "IdentitySource": [
        "$request.header.Authorization"
    ],
    "JwtConfiguration": {
        "Audience": [
            "123456abc"
        ],
        "Issuer": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_abc123"
    },
    "Name": "my-jwt-authorizer"
}

For more information, see Controlling access to HTTP APIs with JWT authorizers in the Amazon API Gateway Developer Guide.

  • For API details, see GetAuthorizer in Amazon CLI Command Reference.

The following code example shows how to use get-authorizers.

Amazon CLI

To retrieve a list of authorizers for an API

The following get-authorizers example displays a list of all of the authorizers for an API.

aws apigatewayv2 get-authorizers \
    --api-id a1b2c3d4

Output:

{
    "Items": [
        {
            "AuthorizerId": "a1b2c3",
            "AuthorizerType": "JWT",
            "IdentitySource": [
                "$request.header.Authorization"
            ],
            "JwtConfiguration": {
                "Audience": [
                    "123456abc"
                ],
                "Issuer": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_abc123"
            },
            "Name": "my-jwt-authorizer"
        },
        {
            "AuthorizerId": "a1b2c4",
            "AuthorizerType": "JWT",
            "IdentitySource": [
                "$request.header.Authorization"
            ],
            "JwtConfiguration": {
                "Audience": [
                    "6789abcde"
                ],
                "Issuer": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_abc234"
            },
            "Name": "new-jwt-authorizer"
        }
    ]
}

For more information, see Controlling access to HTTP APIs with JWT authorizers in the Amazon API Gateway Developer Guide.

  • For API details, see GetAuthorizers in Amazon CLI Command Reference.

The following code example shows how to use get-deployment.

Amazon CLI

To retrieve information about a deployment

The following get-deployment example displays information about a deployment.

aws apigatewayv2 get-deployment \
    --api-id a1b2c3d4 \
    --deployment-id abcdef

Output:

{
    "AutoDeployed": true,
    "CreatedDate": "2020-04-07T23:58:40Z",
    "DeploymentId": "abcdef",
    "DeploymentStatus": "DEPLOYED",
    "Description": "Automatic deployment triggered by changes to the Api configuration"
}

For more information, see API deployment in the Amazon API Gateway Developer Guide.

  • For API details, see GetDeployment in Amazon CLI Command Reference.

The following code example shows how to use get-deployments.

Amazon CLI

To retrieve a list of deployments

The following get-deployments example displays a list of all of an API's deployments.

aws apigatewayv2 get-deployments \
    --api-id a1b2c3d4

Output:

{
    "Items": [
        {
            "AutoDeployed": true,
            "CreatedDate": "2020-04-07T23:58:40Z",
            "DeploymentId": "abcdef",
            "DeploymentStatus": "DEPLOYED",
            "Description": "Automatic deployment triggered by changes to the Api configuration"
        },
        {
            "AutoDeployed": true,
            "CreatedDate": "2020-04-06T00:33:00Z",
            "DeploymentId": "bcdefg",
            "DeploymentStatus": "DEPLOYED",
            "Description": "Automatic deployment triggered by changes to the Api configuration"
        }
    ]
}

For more information, see API deployment in the Amazon API Gateway Developer Guide.

  • For API details, see GetDeployments in Amazon CLI Command Reference.

The following code example shows how to use get-domain-name.

Amazon CLI

To retrieve information about a custom domain name

The following get-domain-name example displays information about a custom domain name.

aws apigatewayv2 get-domain-name \
    --domain-name api.example.com

Output:

{
    "ApiMappingSelectionExpression": "$request.basepath",
    "DomainName": "api.example.com",
    "DomainNameConfigurations": [
        {
            "ApiGatewayDomainName": "d-1234.execute-api.us-west-2.amazonaws.com",
            "CertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678",
            "EndpointType": "REGIONAL",
            "HostedZoneId": "123456789111",
            "SecurityPolicy": "TLS_1_2",
            "DomainNameStatus": "AVAILABLE"
        }
    ],
    "Tags": {}
}

For more information, see Setting up a regional custom domain name in API Gateway in the Amazon API Gateway Developer Guide.

  • For API details, see GetDomainName in Amazon CLI Command Reference.

The following code example shows how to use get-domain-names.

Amazon CLI

To retrieve a list of custom domain names

The following get-domain-names example displays a list of all of the custom domain names for the current user.

aws apigatewayv2 get-domain-names

Output:

{
    "Items": [
        {
            "ApiMappingSelectionExpression": "$request.basepath",
            "DomainName": "api.example.com",
            "DomainNameConfigurations": [
                {
                    "ApiGatewayDomainName": "d-1234.execute-api.us-west-2.amazonaws.com",
                    "CertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678",
                    "EndpointType": "REGIONAL",
                    "HostedZoneId": "123456789111",
                    "SecurityPolicy": "TLS_1_2",
                    "DomainNameStatus": "AVAILABLE"
                }
            ]
        },
        {
            "ApiMappingSelectionExpression": "$request.basepath",
            "DomainName": "newApi.example.com",
            "DomainNameConfigurations": [
                {
                    "ApiGatewayDomainName": "d-5678.execute-api.us-west-2.amazonaws.com",
                    "CertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678",
                    "EndpointType": "REGIONAL",
                    "HostedZoneId": "123456789222",
                    "SecurityPolicy": "TLS_1_2",
                    "DomainNameStatus": "AVAILABLE"
                }
            ]
        }
    ]
}

For more information, see Setting up a regional custom domain name in API Gateway in the Amazon API Gateway Developer Guide.

  • For API details, see GetDomainNames in Amazon CLI Command Reference.

The following code example shows how to use get-integration.

Amazon CLI

To retrieve information about an integration

The following get-integration example displays information about an integration.

aws apigatewayv2 get-integration \
    --api-id a1b2c3d4 \
    --integration-id a1b2c3

Output:

{
    "ApiGatewayManaged": true,
    "ConnectionType": "INTERNET",
    "IntegrationId": "a1b2c3",
    "IntegrationMethod": "POST",
    "IntegrationType": "AWS_PROXY",
    "IntegrationUri": "arn:aws:lambda:us-west-2:12356789012:function:hello12",
    "PayloadFormatVersion": "2.0",
    "TimeoutInMillis": 30000
}

For more information, see Configuring integrations for HTTP APIs and Setting up WebSocket API integrations in the Amazon API Gateway Developer Guide.

  • For API details, see GetIntegration in Amazon CLI Command Reference.

The following code example shows how to use get-integrations.

Amazon CLI

To retrieve a list of integrations

The following get-integrations example displays a list of all of an API's integrations.

aws apigatewayv2 get-integrations \
    --api-id a1b2c3d4

Output:

{
    "Items": [
        {
            "ApiGatewayManaged": true,
            "ConnectionType": "INTERNET",
            "IntegrationId": "a1b2c3",
            "IntegrationMethod": "POST",
            "IntegrationType": "AWS_PROXY",
            "IntegrationUri": "arn:aws:lambda:us-west-2:123456789012:function:my-function",
            "PayloadFormatVersion": "2.0",
            "TimeoutInMillis": 30000
        },
        {
            "ConnectionType": "INTERNET",
            "IntegrationId": "a1b2c4",
            "IntegrationMethod": "ANY",
            "IntegrationType": "HTTP_PROXY",
            "IntegrationUri": "https://www.example.com",
            "PayloadFormatVersion": "1.0",
            "TimeoutInMillis": 30000
        }
    ]
}

For more information, see Configuring integrations for HTTP APIs and Setting up WebSocket API integrations in the Amazon API Gateway Developer Guide.

The following code example shows how to use get-route.

Amazon CLI

To retrieve information about a route

The following get-route example displays information about a route.

aws apigatewayv2 get-route \
    --api-id a1b2c3d4 \
    --route-id 72jz1wk

Output:

{
    "ApiKeyRequired": false,
    "AuthorizationType": "NONE",
    "RouteId": "72jz1wk",
    "RouteKey": "ANY /pets",
    "Target": "integrations/a1b2c3"
}

For more information, see Working with routes for HTTP APIs in the Amazon API Gateway Developer Guide

  • For API details, see GetRoute in Amazon CLI Command Reference.

The following code example shows how to use get-routes.

Amazon CLI

To retrieve a list of routes

The following get-routes example displays a list of all of an API's routes.

aws apigatewayv2 get-routes \
    --api-id a1b2c3d4

Output:

{
    "Items": [
        {
            "ApiKeyRequired": false,
            "AuthorizationType": "NONE",
            "RouteId": "72jz1wk",
            "RouteKey": "ANY /admin",
            "Target": "integrations/a1b2c3"
        },
        {
            "ApiGatewayManaged": true,
            "ApiKeyRequired": false,
            "AuthorizationType": "NONE",
            "RouteId": "go65gqi",
            "RouteKey": "$default",
            "Target": "integrations/a1b2c4"
        }
    ]
}

For more information, see Working with routes for HTTP APIs in the Amazon API Gateway Developer Guide

  • For API details, see GetRoutes in Amazon CLI Command Reference.

The following code example shows how to use get-stage.

Amazon CLI

To retrieve information about a stage

The following get-stage example displays information about the prod stage of an API.

aws apigatewayv2 get-stage \
    --api-id a1b2c3d4 \
    --stage-name prod

Output:

{
    "CreatedDate": "2020-04-08T00:36:05Z",
    "DefaultRouteSettings": {
        "DetailedMetricsEnabled": false
    },
    "DeploymentId": "x1zwyv",
    "LastUpdatedDate": "2020-04-08T00:36:13Z",
    "RouteSettings": {},
    "StageName": "prod",
    "StageVariables": {
        "function": "my-prod-function"
    },
    "Tags": {}
}

For more information, see Working with stages for HTTP APIs in the Amazon API Gateway Developer Guide.

  • For API details, see GetStage in Amazon CLI Command Reference.

The following code example shows how to use get-stages.

Amazon CLI

To retrieve a list of stages

The following get-stages example lists all of an API's stages.

aws apigatewayv2 get-stages \
    --api-id a1b2c3d4

Output:

{
    "Items": [
        {
            "ApiGatewayManaged": true,
            "AutoDeploy": true,
            "CreatedDate": "2020-04-08T00:08:44Z",
            "DefaultRouteSettings": {
                "DetailedMetricsEnabled": false
            },
            "DeploymentId": "dty748",
            "LastDeploymentStatusMessage": "Successfully deployed stage with deployment ID 'dty748'",
            "LastUpdatedDate": "2020-04-08T00:09:49Z",
            "RouteSettings": {},
            "StageName": "$default",
            "StageVariables": {},
            "Tags": {}
        },
        {
            "AutoDeploy": true,
            "CreatedDate": "2020-04-08T00:35:06Z",
            "DefaultRouteSettings": {
                "DetailedMetricsEnabled": false
            },
            "LastUpdatedDate": "2020-04-08T00:35:48Z",
            "RouteSettings": {},
            "StageName": "dev",
            "StageVariables": {
                "function": "my-dev-function"
            },
            "Tags": {}
        },
        {
            "CreatedDate": "2020-04-08T00:36:05Z",
            "DefaultRouteSettings": {
                "DetailedMetricsEnabled": false
            },
            "DeploymentId": "x1zwyv",
            "LastUpdatedDate": "2020-04-08T00:36:13Z",
            "RouteSettings": {},
            "StageName": "prod",
            "StageVariables": {
                "function": "my-prod-function"
            },
            "Tags": {}
        }
    ]
}

For more information, see Working with stages for HTTP APIs in the Amazon API Gateway Developer Guide.

  • For API details, see GetStages in Amazon CLI Command Reference.

The following code example shows how to use get-tags.

Amazon CLI

To retrieve a list of tags for a resource

The following get-tags example lists all of an API's tags.

aws apigatewayv2 get-tags \
    --resource-arn arn:aws:apigateway:us-west-2::/apis/a1b2c3d4

Output:

{
    "Tags": {
        "owner": "dev-team",
        "environment": "prod"
    }
}

For more information, see Tagging your API Gateway resources in the Amazon API Gateway Developer Guide.

  • For API details, see GetTags in Amazon CLI Command Reference.

The following code example shows how to use get-vpc-link.

Amazon CLI

To retrieve information about a VPC link

The following get-vpc-link example displays information about a VPC link.

aws apigatewayv2 get-vpc-link \
    --vpc-link-id abcd123

Output:

{
    "CreatedDate": "2020-04-07T00:27:47Z",
    "Name": "MyVpcLink",
    "SecurityGroupIds": [
        "sg1234",
        "sg5678"
    ],
    "SubnetIds": [
        "subnet-aaaa",
        "subnet-bbbb"
    ],
    "Tags": {},
    "VpcLinkId": "abcd123",
    "VpcLinkStatus": "AVAILABLE",
    "VpcLinkStatusMessage": "VPC link is ready to route traffic",
    "VpcLinkVersion": "V2"
}

For more information, see Working with VPC links for HTTP APIs in the Amazon API Gateway Developer Guide.

  • For API details, see GetVpcLink in Amazon CLI Command Reference.

The following code example shows how to use get-vpc-links.

Amazon CLI

To retrieve a list of VPC links

The following get-vpc-links example displays a list of all of the VPC links for the current user.

aws apigatewayv2 get-vpc-links

Output:

{
    "Items": [
        {
            "CreatedDate": "2020-04-07T00:27:47Z",
            "Name": "MyVpcLink",
            "SecurityGroupIds": [
                "sg1234",
                "sg5678"
            ],
            "SubnetIds": [
                "subnet-aaaa",
                "subnet-bbbb"
            ],
            "Tags": {},
            "VpcLinkId": "abcd123",
            "VpcLinkStatus": "AVAILABLE",
            "VpcLinkStatusMessage": "VPC link is ready to route traffic",
            "VpcLinkVersion": "V2"
        }
        {
            "CreatedDate": "2020-04-07T00:27:47Z",
            "Name": "MyOtherVpcLink",
            "SecurityGroupIds": [
                "sg1234",
                "sg5678"
            ],
            "SubnetIds": [
                "subnet-aaaa",
                "subnet-bbbb"
            ],
            "Tags": {},
            "VpcLinkId": "abcd456",
            "VpcLinkStatus": "AVAILABLE",
            "VpcLinkStatusMessage": "VPC link is ready to route traffic",
            "VpcLinkVersion": "V2"
        }
    ]
}

For more information, see Working with VPC links for HTTP APIs in the Amazon API Gateway Developer Guide.

  • For API details, see GetVpcLinks in Amazon CLI Command Reference.

The following code example shows how to use import-api.

Amazon CLI

To import an HTTP API

The following import-api example creates an HTTP API from an OpenAPI 3.0 definition file named api-definition.yaml.

aws apigatewayv2 import-api \
    --body file://api-definition.yaml

Contents of api-definition.yaml:

openapi: 3.0.1
info:
    title: My Lambda API
    version: v1.0
paths:
    /hello:
        x-amazon-apigateway-any-method:
            x-amazon-apigateway-integration:
                payloadFormatVersion: 2.0
                type: aws_proxy
                httpMethod: POST
                uri: arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:hello/invocations
                connectionType: INTERNET

Output:

{
    "ApiEndpoint": "https://a1b2c3d4.execute-api.us-west-2.amazonaws.com",
    "ApiId": "a1b2c3d4",
    "ApiKeySelectionExpression": "$request.header.x-api-key",
    "CreatedDate": "2020-04-08T17:19:38+00:00",
    "Name": "My Lambda API",
    "ProtocolType": "HTTP",
    "RouteSelectionExpression": "$request.method $request.path",
    "Tags": {},
    "Version": "v1.0"
}

For more information, see Working with OpenAPI definitions for HTTP APIs in the Amazon API Gateway Developer Guide.

  • For API details, see ImportApi in Amazon CLI Command Reference.

The following code example shows how to use reimport-api.

Amazon CLI

To reimport an HTTP API

The following reimport-api example updates an existing HTTP API to use the OpenAPI 3.0 definition specified in api-definition.yaml.

aws apigatewayv2 reimport-api \
    --body file://api-definition.yaml \
    --api-id a1b2c3d4

Contents of api-definition.yaml:

openapi: 3.0.1
info:
    title: My Lambda API
    version: v1.0
paths:
    /hello:
        x-amazon-apigateway-any-method:
            x-amazon-apigateway-integration:
                payloadFormatVersion: 2.0
                type: aws_proxy
                httpMethod: POST
                uri: arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:12356789012:function:hello/invocations
                connectionType: INTERNET

Output:

{
    "ApiEndpoint": "https://a1b2c3d4.execute-api.us-west-2.amazonaws.com",
    "ApiId": "a1b2c3d4",
    "ApiKeySelectionExpression": "$request.header.x-api-key",
    "CreatedDate": "2020-04-08T17:19:38+00:00",
    "Name": "My Lambda API",
    "ProtocolType": "HTTP",
    "RouteSelectionExpression": "$request.method $request.path",
    "Tags": {},
    "Version": "v1.0"
}

For more information, see Working with OpenAPI definitions for HTTP APIs in the Amazon API Gateway Developer Guide.

  • For API details, see ReimportApi in Amazon CLI Command Reference.

The following code example shows how to use tag-resource.

Amazon CLI

To tag a resource

The following tag-resource example adds a tag with the key name Department and a value of Accounting to the specified API.

aws apigatewayv2 tag-resource \
    --resource-arn arn:aws:apigateway:us-west-2::/apis/a1b2c3d4 \
    --tags Department=Accounting

This command produces no output.

For more information, see Tagging your API Gateway resources in the Amazon API Gateway Developer Guide.

  • For API details, see TagResource in Amazon CLI Command Reference.

The following code example shows how to use untag-resource.

Amazon CLI

To remove tags from a resource

The following untag-resource example removes tags with the key names Project and Owner from the specified API.

aws apigatewayv2 untag-resource \
    --resource-arn arn:aws:apigateway:us-west-2::/apis/a1b2c3d4 \
    --tag-keys Project Owner

This command produces no output.

For more information, see Tagging your API Gateway resources in the Amazon API Gateway Developer Guide.

  • For API details, see UntagResource in Amazon CLI Command Reference.

The following code example shows how to use update-api-mapping.

Amazon CLI

To update an API mapping

The following update-api-mapping example changes an API mapping for a custom domain name. As a result, the base URL using the custom domain name for the specified API and stage becomes https://api.example.com/dev.

aws apigatewayv2 update-api-mapping \
    --api-id a1b2c3d4 \
    --stage dev \
    --domain-name api.example.com \
    --api-mapping-id 0qzs2sy7bh \
    --api-mapping-key dev

Output:

{
    "ApiId": "a1b2c3d4",
    "ApiMappingId": "0qzs2sy7bh",
    "ApiMappingKey": "dev"
    "Stage": "dev"
}

For more information, see Setting up a regional custom domain name in API Gateway in the Amazon API Gateway Developer Guide.

The following code example shows how to use update-api.

Amazon CLI

To enable CORS for an HTTP API

The following update-api example updates the specified API's CORS configuration to allow requests from https://www.example.com.

aws apigatewayv2 update-api \
    --api-id a1b2c3d4 \
    --cors-configuration AllowOrigins=https://www.example.com

Output:

{
    "ApiEndpoint": "https://a1b2c3d4.execute-api.us-west-2.amazonaws.com",
    "ApiId": "a1b2c3d4",
    "ApiKeySelectionExpression": "$request.header.x-api-key",
    "CorsConfiguration": {
        "AllowCredentials": false,
        "AllowHeaders": [
            "header1",
            "header2"
        ],
        "AllowMethods": [
            "GET",
            "OPTIONS"
        ],
        "AllowOrigins": [
            "https://www.example.com"
        ]
    },
    "CreatedDate": "2020-04-08T18:39:37+00:00",
    "Name": "my-http-api",
    "ProtocolType": "HTTP",
    "RouteSelectionExpression": "$request.method $request.path",
    "Tags": {},
    "Version": "v1.0"
}

For more information, see Configuring CORS for an HTTP API in the Amazon API Gateway Developer Guide.

  • For API details, see UpdateApi in Amazon CLI Command Reference.

The following code example shows how to use update-authorizer.

Amazon CLI

To update an authorizer

The following update-authorizer example changes a JWT authorizer's identity source to a header named Authorization.

aws apigatewayv2 update-authorizer \
    --api-id a1b2c3d4 \
    --authorizer-id a1b2c3 \
    --identity-source '$request.header.Authorization'

Output:

{
    "AuthorizerId": "a1b2c3",
    "AuthorizerType": "JWT",
    "IdentitySource": [
        "$request.header.Authorization"
    ],
    "JwtConfiguration": {
        "Audience": [
            "123456abc"
        ],
        "Issuer": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_abc123"
    },
    "Name": "my-jwt-authorizer"
}

For more information, see Controlling access to HTTP APIs with JWT authorizers in the Amazon API Gateway Developer Guide.

The following code example shows how to use update-deployment.

Amazon CLI

To change a deployment's description

The following update-deployment example updates a deployment's description.

aws apigatewayv2 update-deployment \
    --api-id a1b2c3d4 \
    --deployment-id abcdef \
    --description 'Manual deployment to fix integration test failures.'

Output:

{
    "AutoDeployed": false,
    "CreatedDate": "2020-02-05T16:21:48+00:00",
    "DeploymentId": "abcdef",
    "DeploymentStatus": "DEPLOYED",
    "Description": "Manual deployment to fix integration test failures."
}

For more information, see Developing an HTTP API in API Gateway in the Amazon API Gateway Developer Guide.

The following code example shows how to use update-domain-name.

Amazon CLI

To update a custom domain name

The following update-domain-name example specifies a new ACM certificate for the api.example.com custom domain name.

aws apigatewayv2 update-domain-name \
    --domain-name api.example.com \
    --domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678

Output:

{
    "ApiMappingSelectionExpression": "$request.basepath",
    "DomainName": "regional.example.com",
    "DomainNameConfigurations": [
        {
            "ApiGatewayDomainName": "d-id.execute-api.us-west-2.amazonaws.com",
            "CertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678",
            "EndpointType": "REGIONAL",
            "HostedZoneId": "123456789111",
            "SecurityPolicy": "TLS_1_2",
            "DomainNameStatus": "AVAILABLE"
        }
    ]
}

For more information, see Setting up a regional custom domain name in API Gateway in the Amazon API Gateway Developer Guide.

The following code example shows how to use update-integration.

Amazon CLI

To update a Lambda integration

The following update-integration example updates an existing Amazon Lambda integration to use the specified Lambda function.

aws apigatewayv2 update-integration \
    --api-id a1b2c3d4 \
    --integration-id a1b2c3 \
    --integration-uri arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:my-new-function/invocations

Output:

{
    "ConnectionType": "INTERNET",
    "IntegrationId": "a1b2c3",
    "IntegrationMethod": "POST",
    "IntegrationType": "AWS_PROXY",
    "IntegrationUri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:my-new-function/invocations",
    "PayloadFormatVersion": "2.0",
    "TimeoutInMillis": 5000
}

For more information, see Configuring integrations for HTTP APIs and Setting up WebSocket API integrations in the Amazon API Gateway Developer Guide.

The following code example shows how to use update-route.

Amazon CLI

Example 1: To update the integration of a route

The following update-route example updates the integration of a specified route.

aws apigatewayv2 update-route \
    --api-id a1b2c3d4 \
    --route-id a1b2c3 \
    --target integrations/a1b2c6

Output:

{
    "ApiKeyRequired": false,
    "AuthorizationType": "NONE",
    "RouteId": "a1b2c3",
    "RouteKey": "ANY /pets",
    "Target": "integrations/a1b2c6"
}

Example 2: To add an authorizer to a route

The following update-route example updates the specified route to use a JWT authorizer.

aws apigatewayv2 update-route \
    --api-id a1b2c3d4  \
    --route-id a1b2c3  \
    --authorization-type JWT \
    --authorizer-id a1b2c5 \
    --authorization-scopes user.id user.email

Output:

{
    "ApiKeyRequired": false,
    "AuthorizationScopes": [
        "user.id",
        "user.email"
    ],
    "AuthorizationType": "JWT",
    "AuthorizerId": "a1b2c5",
    "OperationName": "GET HTTP",
    "RequestParameters": {},
    "RouteId": "a1b2c3",
    "RouteKey": "GET /pets",
    "Target": "integrations/a1b2c6"
}

For more information, see Controlling access to HTTP APIs with JWT authorizers in the Amazon API Gateway Developer Guide.

  • For API details, see UpdateRoute in Amazon CLI Command Reference.

The following code example shows how to use update-stage.

Amazon CLI

To configure custom throttling

The following update-stage example configures custom throttling for the specified stage and route of an API.

aws apigatewayv2 update-stage \
    --api-id a1b2c3d4 \
    --stage-name dev \
    --route-settings '{"GET /pets":{"ThrottlingBurstLimit":100,"ThrottlingRateLimit":2000}}'

Output:

{
    "CreatedDate": "2020-04-05T16:21:16+00:00",
    "DefaultRouteSettings": {
        "DetailedMetricsEnabled": false
    },
    "DeploymentId": "shktxb",
    "LastUpdatedDate": "2020-04-08T22:23:17+00:00",
    "RouteSettings": {
        "GET /pets": {
            "ThrottlingBurstLimit": 100,
            "ThrottlingRateLimit": 2000.0
        }
    },
    "StageName": "dev",
    "StageVariables": {},
    "Tags": {}
}

For more information, see Protecting your HTTP API in the Amazon API Gateway Developer Guide.

  • For API details, see UpdateStage in Amazon CLI Command Reference.

The following code example shows how to use update-vpc-link.

Amazon CLI

To update a VPC link

The following update-vpc-link example updates the name of a VPC link. After you've created a VPC link, you can't change its security groups or subnets.

aws apigatewayv2 update-vpc-link \
    --vpc-link-id abcd123 \
    --name MyUpdatedVpcLink

Output:

{
    "CreatedDate": "2020-04-07T00:27:47Z",
    "Name": "MyUpdatedVpcLink",
    "SecurityGroupIds": [
        "sg1234",
        "sg5678"
    ],
    "SubnetIds": [
        "subnet-aaaa",
        "subnet-bbbb"
    ],
    "Tags": {},
    "VpcLinkId": "abcd123",
    "VpcLinkStatus": "AVAILABLE",
    "VpcLinkStatusMessage": "VPC link is ready to route traffic",
    "VpcLinkVersion": "V2"
}

For more information, see Working with VPC links for HTTP APIs in the Amazon API Gateway Developer Guide.

  • For API details, see UpdateVpcLink in Amazon CLI Command Reference.