This documentation is for Version 1 of the Amazon CLI only. For documentation related to Version 2 of the Amazon CLI, see the Version 2 User Guide.
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.
Each example includes a link to the complete source code, 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 thetest
stage of an API to the/myApi
path of theregional.example.com
custom domain name.aws apigatewayv2 create-api-mapping \ --domain-name
regional.example.com
\ --api-mapping-keymyApi
\ --api-ida1b2c3d4
\ --stagetest
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. -
For API details, see CreateApiMapping
in Amazon CLI Command Reference.
-
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-typeHTTP
\ --targetarn: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-typeWEBSOCKET
\ --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-ida1b2c3d4
\ --authorizer-typeJWT
\ --identity-source '$request.header.Authorization
' \ --jwt-configurationAudience=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. -
For API details, see CreateAuthorizer
in Amazon CLI Command Reference.
-
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 thedev
stage of the API.aws apigatewayv2 create-deployment \ --api-id
a1b2c3d4
\ --stage-namedev
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. -
For API details, see CreateDeployment
in Amazon CLI Command Reference.
-
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-configurationsCertificateArn=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. -
For API details, see CreateDomainName
in Amazon CLI Command Reference.
-
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-behaviorWHEN_NO_MATCH
\ --timeout-in-millis29000
\ --connection-typeINTERNET
\ --integration-typeMOCK
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-typeAWS_PROXY
\ --integration-uriarn:aws:lambda:us-west-2:123456789012:function:my-function
\ --payload-format-version2.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. -
For API details, see CreateIntegration
in Amazon CLI Command Reference.
-
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 namedsignup
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-namedev
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-idssubnet-aaaa
subnet-bbbb
\ --security-group-idssg1234
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. -
For API details, see DeleteAccessLogSettings
in Amazon CLI Command Reference.
-
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 theapi.example.com
custom domain name.aws apigatewayv2 delete-api-mapping \ --api-mapping-id
a1b2c3
\ --domain-nameapi.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. -
For API details, see DeleteApiMapping
in Amazon CLI Command Reference.
-
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-ida1b2c3
This command produces no output.
For more information, see Controlling access to HTTP APIs with JWT authorizers
in the Amazon API Gateway Developer Guide. -
For API details, see DeleteAuthorizer
in Amazon CLI Command Reference.
-
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. -
For API details, see DeleteCorsConfiguration
in Amazon CLI Command Reference.
-
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-ida1b2c3
This command produces no output.
For more information, see API deployment
in the Amazon API Gateway Developer Guide. -
For API details, see DeleteDeployment
in Amazon CLI Command Reference.
-
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. -
For API details, see DeleteDomainName
in Amazon CLI Command Reference.
-
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-ida1b2c3
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. -
For API details, see DeleteIntegration
in Amazon CLI Command Reference.
-
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-namedev
\ --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. -
For API details, see DeleteRouteSettings
in Amazon CLI Command Reference.
-
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-ida1b2c3
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 thetest
stage of an API.aws apigatewayv2 delete-stage \ --api-id
a1b2c3d4
\ --stage-nametest
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 namedprod
to a YAML file namedstage-definition.yaml
. The exported definition file includes API Gateway extensions by default.aws apigatewayv2 export-api \ --api-id
a1b2c3d4
\ --output-typeYAML
\ --specificationOAS30
\ --stage-nameprod
\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 theapi.example.com
custom domain name.aws apigatewayv2 get-api-mapping \ --api-mapping-id
a1b2c3
\ --domain-nameapi.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 theapi.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-ida1b2c3
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-idabcdef
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-ida1b2c3
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. -
For API details, see GetIntegrations
in Amazon CLI Command Reference.
-
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-id72jz1wk
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 theprod
stage of an API.aws apigatewayv2 get-stage \ --api-id
a1b2c3d4
\ --stage-nameprod
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 namedapi-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 inapi-definition.yaml
.aws apigatewayv2 reimport-api \ --body
file://api-definition.yaml
\ --api-ida1b2c3d4
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 nameDepartment
and a value ofAccounting
to the specified API.aws apigatewayv2 tag-resource \ --resource-arn
arn:aws:apigateway:us-west-2::/apis/a1b2c3d4
\ --tagsDepartment=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 namesProject
andOwner
from the specified API.aws apigatewayv2 untag-resource \ --resource-arn
arn:aws:apigateway:us-west-2::/apis/a1b2c3d4
\ --tag-keysProject
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 becomeshttps://api.example.com/dev
.aws apigatewayv2 update-api-mapping \ --api-id
a1b2c3d4
\ --stagedev
\ --domain-nameapi.example.com
\ --api-mapping-id0qzs2sy7bh
\ --api-mapping-keydev
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. -
For API details, see UpdateApiMapping
in Amazon CLI Command Reference.
-
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 fromhttps://www.example.com
.aws apigatewayv2 update-api \ --api-id
a1b2c3d4
\ --cors-configurationAllowOrigins=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 namedAuthorization
.aws apigatewayv2 update-authorizer \ --api-id
a1b2c3d4
\ --authorizer-ida1b2c3
\ --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. -
For API details, see UpdateAuthorizer
in Amazon CLI Command Reference.
-
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-idabcdef
\ --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. -
For API details, see UpdateDeployment
in Amazon CLI Command Reference.
-
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 theapi.example.com
custom domain name.aws apigatewayv2 update-domain-name \ --domain-name
api.example.com
\ --domain-name-configurationsCertificateArn=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. -
For API details, see UpdateDomainName
in Amazon CLI Command Reference.
-
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-ida1b2c3
\ --integration-uriarn: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. -
For API details, see UpdateIntegration
in Amazon CLI Command Reference.
-
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-ida1b2c3
\ --targetintegrations/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-ida1b2c3
\ --authorization-typeJWT
\ --authorizer-ida1b2c5
\ --authorization-scopesuser.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-namedev
\ --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
\ --nameMyUpdatedVpcLink
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.
-