Set up an edge-optimized API using AWS CLI commands
Setting up an API using the AWS CLI requires working with the create-rest-api
, create-resource
or get-resources
, put-method
,
put-method-response
, put-integration
, and put-integration-response
commands. The following procedures
show how to work with these AWS CLI commands to create the simple PetStore API of the
HTTP
integration type.
To create a simple PetStore API using AWS CLI
-
Call the
create-rest-api
command to set up theRestApi
in a specific region (us-west-2
).aws apigateway create-rest-api --name 'Simple PetStore (AWS CLI)' --region us-west-2
The following is the output of this command:
{ "id": "vaz7da96z6", "name": "Simple PetStore (AWS CLI)", "createdDate": "2022-12-15T08:07:04-08:00", "apiKeySource": "HEADER", "endpointConfiguration": { "types": [ "EDGE" ] }, "disableExecuteApiEndpoint": false }
Note the returned
id
of the newly createdRestApi
. You need it to set up other parts of the API. -
Call the
get-resources
command to retrieve the root resource identifier of theRestApi
.aws apigateway get-resources --rest-api-id vaz7da96z6 --region us-west-2
The following is the output of this command:
{ "items": [ { "id": "begaltmsm8", "path": "/" } ] }
Note the root resource
Id
. You need it to start setting the API's resource tree and configuring methods and integrations. -
Call the
create-resource
command to append a child resource (pets
) under the root resource (begaltmsm8
):aws apigateway create-resource --rest-api-id vaz7da96z6 \ --region us-west-2 \ --parent-id begaltmsm8 \ --path-part pets
The following is the output of this command:
{ "id": "6sxz2j", "parentId": "begaltmsm8", "pathPart": "pets", "path": "/pets" }
To append a child resource under the root, you specify the root resource
Id
as theparentId
property value. Similarly, to append a child resource under thepets
resource, you repeat the preceding step while replacing theparent-id
value with thepets
resourceid
of6sxz2j
:aws apigateway create-resource --rest-api-id vaz7da96z6 \ --region us-west-2 \ --parent-id 6sxz2j \ --path-part '{petId}'
To make a path part a path parameter, enclose it in a pair of curly brackets. If successful, this command returns the following response:
{ "id": "rjkmth", "parentId": "6sxz2j", "path": "/pets/{petId}", "pathPart": "{petId}" }
Now that you created two resources:
/pets
(6sxz2j
) and/pets/{petId}
(rjkmth
), you can proceed to set up methods on them. -
Call the
put-method
command to add theGET
HTTP method on the/pets
resource. This creates an APIMethod
ofGET /pets
with open access, referencing the/pets
resource by its ID value of6sxz2j
.aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --authorization-type "NONE" \ --region us-west-2
The following is the successful output of this command:
{ "httpMethod": "GET", "authorizationType": "NONE", "apiKeyRequired": false }
The method is for open access because
authorization-type
is set toNONE
. To permit only authenticated users to call the method, you can use IAM roles and policies, a Lambda authorizer (formerly known as a custom authorizer), or an Amazon Cognito user pool. For more information, see Controlling and managing access to a REST API in API Gateway.To enable read access to the
/pets/{petId}
resource (rjkmth
), add theGET
HTTP method on it to create an APIMethod
ofGET /pets/{petId}
as follows.aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id rjkmth --http-method GET \ --authorization-type "NONE" \ --region us-west-2 \ --request-parameters method.request.path.petId=true
The following is the successful output of this command:
{ "httpMethod": "GET", "authorizationType": "NONE", "apiKeyRequired": false, "requestParameters": { "method.request.path.petId": true } }
Note that the method request path parameter of
petId
must be specified as a required request parameter for its dynamically set value to be mapped to a corresponding integration request parameter and passed to the backend. -
Call the
put-method-response
command to set up the 200 OK response of theGET /pets
method, specifying the/pets
resource by its ID value of6sxz2j
.aws apigateway put-method-response --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j --http-method GET \ --status-code 200 --region us-west-2
The following is the output of this command:
{ "statusCode": "200" }
Similarly, to set the 200 OK response of the
GET /pets/{petId}
method, do the following, specifying the/pets/{petId}
resource by its resource ID value ofrjkmth
:aws apigateway put-method-response --rest-api-id vaz7da96z6 \ --resource-id rjkmth --http-method GET \ --status-code 200 --region us-west-2
Having set up a simple client interface for the API, you can proceed to set up the integration of the API methods with the backend.
-
Call the
put-integration
command to set up anIntegration
with a specified HTTP endpoint for theGET /pets
method. The/pets
resource is identified by its resource Id6sxz2j
:aws apigateway put-integration --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j --http-method GET --type HTTP \ --integration-http-method GET \ --uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets' \ --region us-west-2
The following is the output of this command:
{ "type": "HTTP", "httpMethod": "GET", "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "connectionType": "INTERNET", "passthroughBehavior": "WHEN_NO_MATCH", "timeoutInMillis": 29000, "cacheNamespace": "6sxz2j", "cacheKeyParameters": [] }
Notice that the integration
uri
ofhttp://petstore-demo-endpoint.execute-api.com/petstore/pets
specifies the integration endpoint of theGET /pets
method.Similarly, you create an integration request for the
GET /pets/{petId}
method as follows:aws apigateway put-integration \ --rest-api-id vaz7da96z6 \ --resource-id rjkmth \ --http-method GET \ --type HTTP \ --integration-http-method GET \ --uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}' \ --request-parameters '{"integration.request.path.id":"method.request.path.petId"}' \ --region us-west-2
Here, the integration endpoint,
uri
ofhttp://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}
, also uses a path parameter (id
). Its value is mapped from the corresponding method request path parameter of{petId}
. The mapping is defined as part of therequest-parameters
. If this mapping is not defined here, the client gets an error response when trying to call the method.The following is the output of this command:
{ "type": "HTTP", "httpMethod": "GET", "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}", "connectionType": "INTERNET", "requestParameters": { "integration.request.path.id": "method.request.path.petId" }, "passthroughBehavior": "WHEN_NO_MATCH", "timeoutInMillis": 29000, "cacheNamespace": "rjkmth", "cacheKeyParameters": [] }
-
Call the
put-integration-response
command to create anIntegrationResponse
of theGET /pets
method integrated with an HTTP backend.aws apigateway put-integration-response --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j --http-method GET \ --status-code 200 --selection-pattern "" \ --region us-west-2
The following is the output of this command:
{ "statusCode": "200", "selectionPattern": "" }
Similarly, call the following
put-integration-response
command to create anIntegrationResponse
of theGET /pets/{petId}
method:aws apigateway put-integration-response --rest-api-id vaz7da96z6 \ --resource-id rjkmth --http-method GET --status-code 200 --selection-pattern "" --region us-west-2
With the preceding steps, you finished setting up a simple API that allows your customers to query available pets on the PetStore website and to view an individual pet of a specified identifier. To make it callable by your customer, you must deploy the API.
-
Deploy the API to a
stage
stage, for example, by callingcreate-deployment
:aws apigateway create-deployment --rest-api-id vaz7da96z6 \ --region us-west-2 \ --stage-name test \ --stage-description 'Test stage' \ --description 'First deployment'
The following is the output of this command:
{ "id": "ab1c1d", "description": "First deployment", "createdDate": "2022-12-15T08:44:13-08:00" }
You can test this API by typing the
https://vaz7da96z6.execute-api.us-west-2.amazonaws.com/test/pets
URL in a browser, and substituting vaz7da96z6
with the identifier of
your API. The expected output should be as follows:
[ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ]
To test the GET /pets/{petId}
method, type
https://vaz7da96z6.execute-api.us-west-2.amazonaws.com/test/pets/3
in the browser. You should receive the following response:
{ "id": 3, "type": "fish", "price": 0.99 }