Menu
Amazon API Gateway
Developer Guide

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.

  1. From Create new API, select New API, type a name in API Name, optionally add a description in Description, and then choose Create API.

    
                            Create an API manually

    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 /pets resource 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.

  2. To create the /pets resource, select the root, choose Actions and then choose Create Resource.

    
                            Create a resource

    Type Pets in Resource Name, leave the Resource Path value as given, and choose Create Resource.

    
                            Create a resource Part B
  3. To expose a GET method on the /pets resource, choose Actions and then Create Method.

    
                            Create method on a resource

    Choose GET from the list under the /pets resource node and choose the check mark icon to finish creating the method.

    
                            Create method on a resource

    Note

    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 backend. The next step sets this up.

  4. 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/pets as the Endpoint URL value, leave all other settings as default, and then choose Save.

    Note

    For the integration request's HTTP method, you must choose one supported by the backend. For HTTP or 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 POST to invoke the function, whereas the method request may use any HTTP verb depending on the logic of the Lambda function.

    
                            Integrate GET on Pets with PetStore site

    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 Pet items by the pet type (e.g., "Dog" or "Cat") on a given page. It uses the type and page query 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.

  5. In the GET method's Method Execution pane, choose Method Request, select AWS_IAM for Authorization, expand the URL Query String Parameters section, and choose Add query string to create two query string parameters named type and page. Choose the check mark icon to save the newly added query string parameters.

    
                            Add query strings to GET on Pets method request

    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 backend. Because the method uses AWS_IAM, you must sign the request to invoke the method.

  6. 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.

    
                            Map query strings to GET on Pets from method request to integration request

    This completes building the simple demo API. It's time to test the API.

  7. To test the API using the API Gateway console, choose Test on the Method Execution pane for the GET /pets method. In the Method Test pane, enter Dog and 2 for the type and page query strings, respectively, and then choose Test.

    
                            Test-invoke GET on Pets method

    The result is shown as follows. (You may need to scroll down to see the test result.)

    
                            Test-invoke GET on Pets method result

    Now that the test is successful, we can deploy the API to make it publicly available.

  8. To deploy the API, select the API and then choose Deploy API from the Actions drop-down menu.

    
                            Deploy API

    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.

    
                            Deploy API part 2

    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:

    
                            Get invoke URL

    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_IAM authorization 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, 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
    https://api-id.execute-api.region.amazonaws.com/test/pets?type=Dog&page=2

    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.

    
                            Get invoke URL

    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.

    Note

    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.