Build the API Step By Step
This section walks you through the steps to create resources, expose methods on a resource, configure a method to achieve the desired API behaviors, and to test and deploy the API.
From Create new API, select New API, type a name in API Name, optionally add a description in Description, and then choose Create API.
As a result, an empty API is created. The Resources tree shows the root resource (
/) without any methods. In this exercise, we will build the API with the HTTP integration of the PetStore demo website (http://petstore-demo-endpoint.execute-api.com.) For illustration purposes, we will create a
/petsresource as a child of the root and expose a GET method on this resource for a client to retrieve a list of available Pets items from the PetStore website.
To create the
/petsresource, select the root, choose Actions and then choose Create Resource.
Petsin Resource Name, leave the Resource Path value as given, and choose Create Resource.
To expose a GET method on the
/petsresource, choose Actions and then Create Method.
Choose GET from the list under the /pets resource node and choose the check mark icon to finish creating the method.
Other options for an API method include:
POST, primarily used to create child resources.
PUT, primarily used to update existing resources (and, although not recommended, can be used to create child resources).
DELETE, used to delete resources.
PATCH, used to update resources.
HEAD, primarily used in testing scenarios. It is the same as GET but does not return the resource representation.
OPTIONS, which can be used by callers to get information about available communication options for the target service.
The method created is not yet integrated with the back end. The next step sets this up.
In the method's Setup pane, select HTTP for Integration type, select GET from the HTTP method drop-down list, type
http://petstore-demo-endpoint.execute-api.com/petstore/petsas the Endpoint URL value, and then choose Save.
For the integration request's HTTP method, you must choose one supported by the back end. For
Mock integration, it makes sense that the method request and the integration request use the same HTTP verb. For other integration types the method request will likely use an HTTP verb different from the integration request. For example, to call a Lambda function, the integration request must use
POSTto invoke the function, whereas the method request may use any HTTP verb depending on the logic of the Lambda function.
When the method setup finishes, you are presented with the Method Execution pane, where you can further configure the method request to add query string or custom header parameters. You can also update the integration request to map input data from the method request to the format required by the back end.
The PetStore website allows you to retrieve a list of
Petitems by the pet type (e.g., "Dog" or "Cat") on a given page. It uses the
pagequery string parameters to accept such input. As such, we must add the query string parameters to the method request and map them into the corresponding query strings of the integration request.
In the GET method's Method Execution pane, choose Method Request, select
AWS_IAMfor Authorization, expand the URL Query String Parameters section, and choose Add query string to create two query string parameters named
page. Choose the check mark icon to save the newly added query string parameters.
The client can now supply a pet type and a page number as query string parameters when submitting a request. These input parameters must be mapped into the integration's query string parameters to forward the input values to our PetStore website in the back end. Because the method uses
AWS_IAM, you must sign the request to invoke the method.
From the method's Integration Request page, expand the URL Query String Parameters section. By default, the method request query string parameters are mapped to the like-named integration request query string parameters. This default mapping works for our demo API. We will leave them as given. To map a different method request parameter to the corresponding integration request parameter, choose the pencil icon for the parameter to edit the mapping expression, shown in the Mapped from column. To map a method request parameter to a different integration request parameter, first choose the delete icon to remove the existing integration request parameter, choose Add query string to specify a new name and the desired method request parameter mapping expression.
This completes building the simple demo API. It's time to test the API.
To test the API using the API Gateway console, choose Test from the GET-on-Pets method's Method Execution pane. In the Method Test pane, enter
2for the type and page query strings, respectively, and then choose Test.
The result is shown as follows. (You may need to scroll down to see the test result.)
Now that the test is successful, we can deploy the API to make it publicly available.
To deploy the API, select the API and then choose Deploy API from the Actions drop-down menu.
In the Deploy API dialog, choose a stage (or
[New Stage]for the API's first deployment); enter a name (e.g., "test", "prod", "dev", etc.) in the Stage name input field; optionally, provide a description in Stage description and/or Deployment description; and then choose Deploy.
Once deployed, you can obtain the invocation URLs (Invoke URL) of the API's endpoints. For example, the GET method on the Pets resource invocation URL is as follows:
If the GET method supported anonymous access, (for example, if the method's authorization type were set to
NONE) you could double-click the Invoke URL link to invoke the method in your default browser. If needed, you could also append necessary query string parameters to the invocation URL. With the
AWS_IAMauthorization type described here, you must sign the request with an access key ID and the corresponding secret key of an IAM user of your AWS account. To do this, you must use a client that supports the Signature Version 4 (SigV4) protocols. An example of such a client is an app that uses one of the AWS SDKs or the Postman Chrome browser extension. To call a POST, PUT, or PATCH method, you also need to use such a client to handle the payload.
To invoke this API method in the Postman extension, append the query string parameters to the stage-specific method invocation URL (as shown in the previous image) to create the complete method request URL:Copy
Specify this URL in the address bar of the browser. Choose GET as the HTTP verb. Select AWS Signature for the Type option under the Authorization tab, and then specify the following required properties before sending the request:
For AccessKey, type the caller's AWS access key, as provisioned from AWS IAM.
For SecretKey, type the caller's AWS secret key, as provisioned from AWS IAM when the access key was first created.
For AWS Region, type the API-hosting AWS Region, as specified in the invocation URL.
For Service Name, type
execute-api, for the API Gateway execution service.
If you use an SDK to create a client, you can call the methods exposed by the SDK to sign the request. For implementation details, see the AWS SDK of your choosing.
When changes are made to your API, you must redeploy the API to make the new or updated features available before invoking the request URL again.