Menu
Amazon API Gateway
Developer Guide

Map Request Parameters for an API Gateway API

In this walkthrough, you will learn how to map method request parameters to the corresponding integration request parameters for an API Gateway API. As an illustration, we will create an example API with the HTTP integration and use it to demonstrate how to use API Gateway to map a method request parameter to the corresponding integration request parameter and to access the publicly accessible HTTP endpoint of:

Copy
http://petstore-demo-endpoint.execute-api.com/petstore/pets

If you copy the above URL, paste it into the address bar of a web browser, and hit the Enter or Return key, you will get the following JSON-formatted response body:

Copy
[ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ]

The above endpoint can take two query parameters: type and page. For example, if you change the above URL to the following:

Copy
http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=cat&page=2

you will receive the following JSON-formatted response payload, displaying page 2 of only the cats:

Copy
[ { "id": 4, "type": "cat", "price": 999.99 }, { "id": 5, "type": "cat", "price": 249.99 }, { "id": 6, "type": "cat", "price": 49.97 } ]

This endpoint also supports the use of an item ID, as expressed by a URL path parameter. For example, if you browse to the following:

Copy
http://petstore-demo-endpoint.execute-api.com/petstore/pets/1

The following JSON-formatted information about the item with an ID of 1 is displayed:

Copy
{ "id": 1, "type": "dog", "price": 249.99 }

In addition to supporting GET operations, this endpoint also take POST requests with a payload. For example, if you use Postman to send a POST method request to the following:

Copy
http://petstore-demo-endpoint.execute-api.com/petstore/pets

including the header Content-type: application/json and the following request body:

Copy
{ "type": "dog", "price": 249.99 }

you will receive following JSON object in the response body:

Copy
{ "pet": { "type": "dog", "price": 249.99 }, "message": "success" }

We now expose these and other features by building an API Gateway API with the HTTP integration of this PetStore website. The tasks includes the following:

  • Create an API with a resource of https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets acting as a proxy to the HTTP endpoint of http://petstore-demo-endpoint.execute-api.com/petstore/pets.

  • Enable the API to accept two method request query parameters of petType and petsPage, map them to the type and page query parameters of the integration request, respectively, and pass the request to the HTTP endpoint.

  • Support a path parameter of {petId} on the API's method request URL to specify an item ID, map it to the {id} path parameter in the integration request URL, and send the request to the HTTP endpoint.

  • Enable the method request to accept the JSON payload of the format defined by the backend website, pass the payload without modifications through the integration request to the backend HTTP endpoint.

Note

Pay attention to the casing used in the steps of this walkthrough. Typing a lowercase letter instead of an uppercase letter (or vice versa) can cause errors later in the walkthrough.

Prerequisites

Before you begin this walkthrough, you should do the following:

  1. Complete the steps in Get Ready to Use API Gateway, including assigning API Gateway access permission to the IAM user.

  2. At a minimum, follow the steps in Build an API Gateway API to Expose an HTTP Endpoint to create a new API named MyDemoAPI in the API Gateway console.

Step 1: Create Resources

In this step, you will create three resources that will enable the API to interact with the HTTP endpoint.

To create the first resource

  1. In the Resources pane, select the resource root, as represented by a single forward slash (/), and then choose Create Resource from the Actions drop-down menu.

  2. For Resource Name, type petstorewalkthrough.

  3. For Resource Path, accept the default of /petstorewalkthrough, and then choose Create Resource.

To create the second resource

  1. In the Resources pane, choose /petstorewalkthrough, and then choose Create Resource.

  2. For Resource Name, type pets.

  3. For Resource Path, accept the default of /petstorewalkthrough/pets, and then choose Create Resource.

To create the third resource

  1. In the Resources pane, choose /petstorewalkthrough/pets, and then choose Create Resource.

  2. For Resource Name, type petId. This maps to the item ID in the HTTP endpoint.

  3. For Resource Path, overwrite petid with {petId}. Be sure to use curly braces ({ }) around petId so that /petstorewalkthrough/pets/{petId} is displayed, and then choose Create Resource.

    This maps to /petstore/pets/my-item-id in the HTTP endpoint.

Step 2: Create and Test the Methods

In this step, you will integrate the methods with the backend HTTP endpoints, map the GET method request parameters to the corresponding integration request parameters, and then test the methods.

To set up and test the first GET method

This procedure demonstrates the following:

  • Create and integrate the method request of GET /petstorewalkthrough/pets with the integration request of GET http://petstore-demo-endpoint.execute-api.com/petstore/pets.

  • Map the method request query parameters of petType and petsPage to the integration request query string parameters of type and page, respectively.

  1. In the Resources pane, choose /petstorewalkthrough/pets, choose Create Method from the Actions menu, and then choose GET under /pets from the drop-down list of the method names.

  2. In the /petstorewalkthrough/pets - GET - Setup pane, choose HTTP for Integration type and choose GET for HTTP method.

  3. For Endpoint URL, type http://petstore-demo-endpoint.execute-api.com/petstore/pets.

  4. Choose Save.

  5. In the Method Execution pane, choose Method Request, and then choose the arrow next to URL Query String Parameters.

  6. Choose Add query string.

  7. For Name, type petType.

    This specifies the petType query parameter in the API's method request.

  8. Choose the check mark icon to finish creating the method request URL query string parameter.

  9. Choose Add query string again.

  10. For Name, type petsPage.

    This specifies the petsPage query parameter in the API's method request.

  11. Choose the check mark icon to finish creating the method request URL query string parameter.

  12. Choose Method Execution, choose Integration Request, and then choose the arrow next to URL Query String Parameters.

  13. Delete the petType entry mapped from method.request.querystring.petType and the petsPage entry mapped from method.request.querystring.petsPage. This is because the endpoint expects query string parameters named type and page for the request URL, instead of the default values.

  14. Choose Add query string

  15. For Name, type type. This creates the required query string parameter for the integration request URL.

  16. For Mapped from, type method.request.querystring.petType.

    This maps the method request's petType query parameter to the integration request's type query parameter.

  17. Choose the check mark icon to finish creating the integration request URL query string parameter.

  18. Choose Add query string again.

  19. For Name, type page. This creates the required query string parameter for the integration request URL.

  20. For Mapped from, type method.request.querystring.petsPage.

    This maps the method request's petsPage query parameter to the integration request's page query parameter.

  21. Choose the check mark icon to finish creating the integration request URL query string parameter.

  22. Choose Method Execution, and in the Client box, choose TEST. In the Query Strings area, for petType, type cat. For petsPage, type 2.

  23. Choose Test. If successful, Response Body will display the following:

    Copy
    [ { "id": 4, "type": "cat", "price": 999.99 }, { "id": 5, "type": "cat", "price": 249.99 }, { "id": 6, "type": "cat", "price": 49.97 } ]

To set up and test the second GET method

This procedure demonstrates the following:

  • Create and integrate the method request of GET /petstorewalkthrough/pets/{petId} with the integration request of GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}.

  • Map the method request path parameters of petId to the integration request path parameters of id.

  1. In the Resources list, choose /petstorewalkthrough/pets/{petId}, choose Create Method from the Actions drop-down menu, and then choose GET as the HTTP verb for the method.

  2. In the Setup pane, choose HTTP for Integration type and choose GET for HTTP method.

  3. For Endpoint URL, type http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}.

  4. Choose Save.

  5. In the Method Execution pane, choose Integration Request, and then choose the arrow next to URL Path Parameters.

  6. Choose Add path.

  7. For Name, type id.

  8. For Mapped from, type method.request.path.petId.

    This maps the method request's path parameter of petId to the integration request's path parameter of id.

  9. Choose the check mark icon to finish creating the URL path parameter.

  10. Choose Method Execution, and in the Client box, choose TEST. In the Path area, for petId, type 1.

  11. Choose Test. If successful, Response Body will display the following:

    Copy
    { "id": 1, "type": "dog", "price": 249.99 }

To set up and test the POST method

This procedure demonstrates the following:

  • Create and integrate the method request of POST /petstorewalkthrough/pets with the integration request of POST http://petstore-demo-endpoint.execute-api.com/petstore/pets.

  • Pass the method request JSON payload through to the integration request payload, without modification.

  1. In the Resources pane, choose /petstorewalkthrough/pets, choose Create Method from the Actions drop-down menu, and then choose POST as the HTTP verb for the method.

  2. In the Setup pane, choose HTTP for Integration type and choose POST for HTTP method.

  3. For Endpoint URL, type http://petstore-demo-endpoint.execute-api.com/petstore/pets.

  4. Choose Save.

  5. In the Method Execution pane, in the Client box, choose TEST. Expand Request Body, and then type the following:

    Copy
    { "type": "dog", "price": 249.99 }
  6. Choose Test. If successful, Response Body will display the following:

    Copy
    { "pet": { "type": "dog", "price": 249.99 }, "message": "success" }

Step 3: Deploy the API

In this step, you will deploy the API so that you can begin calling it outside of the API Gateway console.

To deploy the API

  1. In the Resources pane, choose Deploy API.

  2. For Deployment stage, choose test.

    Note

    The input must be UTF-8 encoded (i.e., unlocalized) text.

  3. For Deployment description, type Calling HTTP endpoint walkthrough.

  4. Choose Deploy.

Step 4: Test the API

In this step, you will go outside of the API Gateway console and use your API to access the HTTP endpoint.

  1. In the Stage Editor pane, next to Invoke URL, copy the URL to the clipboard. It should look something like this:

    Copy
    https://my-api-id.execute-api.region-id.amazonaws.com/test
  2. Paste this URL in the address box of a new browser tab.

  3. Append /petstorewalkthrough/pets so that it looks like this:

    Copy
    https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets

    Browse to the URL. The following information should be displayed:

    Copy
    [ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ]
  4. After petstorewalkthrough/pets, type ?petType=cat&petsPage=2 so that it looks like this:

    Copy
    https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets?petType=cat&petsPage=2
  5. Browse to the URL. The following information should be displayed:

    Copy
    [ { "id": 4, "type": "cat", "price": 999.99 }, { "id": 5, "type": "cat", "price": 249.99 }, { "id": 6, "type": "cat", "price": 49.97 } ]
  6. After petstorewalkthrough/pets, replace ?petType=cat&petsPage=2 with /1 so that it looks like this:

    Copy
    https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets/1
  7. Browse to the URL. The following information should be displayed:

    Copy
    { "id": 1, "type": "dog", "price": 249.99 }
  8. Using a web debugging proxy tool or the cURL command-line tool, send a POST method request to the URL from the previous procedure. Be sure to append /petstorewalkthrough/pets so that it looks like this:

    Copy
    https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets

    Also, be sure to append the following header:

    Copy
    Content-Type: application/json

    And be sure to add the following code to the request body:

    Copy
    { "type": "dog", "price": 249.99 }

    For example, if you use the cURL command-line tool, run a command similar to the following:

    Copy
    curl -H "Content-Type: application/json" -X POST -d "{\"type\": \"dog\",\"price\": 249.99}" https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets

    The following information should be returned in the response body:

    Copy
    { "pet": { "type": "dog", "price": 249.99 }, "message": "success" }

You have reached the end of this walkthrough.

Next Steps

You may want to begin the next walkthrough, which shows you how to use models and mappings in API Gateway to transform the output of an API call from one data format to another. See Map Response Payload.