Tutorial: Build a REST API with HTTP non-proxy integration - Amazon API Gateway
Create an API with HTTP custom integrationMap request parametersMap response payload
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Tutorial: Build a REST API with HTTP non-proxy integration

In this tutorial, you create an API from scratch using the Amazon API Gateway console. You can think of the console as an API design studio and use it to scope the API features, to experiment with its behaviors, to build the API, and to deploy your API in stages.

Create an API with HTTP custom integration

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. Sign in to the API Gateway console at https://console.amazonaws.cn/apigateway.

  2. If this is your first time using API Gateway, you see a page that introduces you to the features of the service. Under REST API, choose Build. When the Create Example API popup appears, choose OK.

    If this is not your first time using API Gateway, choose Create API. Under REST API, choose Build.

    1. Choose New API.

    2. Enter a name in API Name.

    3. Optionally, add a brief description in Description.

    4. 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 custom integration of the PetStore website (http://petstore-demo-endpoint.execute-api.com/petstore/pets.) 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.

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

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

  4. To expose a GET method on the /pets resource, 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.

    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.

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

    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.

  6. 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 each query string parameter as you add it.

    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.

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

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

    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.

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

    If the GET method supported open access, (i.e., 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 Amazon credentials. 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 Amazon SDKs or the Postman application or cURL commands.

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

Map request parameters for an API Gateway API

In this walkthrough, we describe how to map method request parameters to the corresponding integration request parameters for an API Gateway API. We create an example API with the HTTP custom integration and use it to demonstrate how to use API Gateway to map a method request parameter to the corresponding integration request parameter. We then access the following publicly accessible HTTP endpoint: 

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 press Enter or Return, you get the following JSON-formatted response body: 

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

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

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

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

[
  {
    "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, browse to the following:

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:

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

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

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

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

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

You receive the following JSON object in the response body:

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

We now expose these and other features by building an API Gateway API with the HTTP custom integration of this PetStore website. The tasks include 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, and pass the payload without modification 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 Prerequisites for getting started with API Gateway.

  2. At a minimum, follow the steps in Tutorial: Build a REST API with HTTP non-proxy integration to create a new API named MyDemoAPI in the API Gateway console.

Step 1: Create resources

In this step, you create three resources that 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}. 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 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. You perform this step because the endpoint requires 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. 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 displays the following:

    [
  {
    "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 displays the following:

    {   
  "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:

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

  6. Choose Test. If successful, Response Body displays the following:

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

Step 3: Deploy the API

In this step, you 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 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:

    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:

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

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

    [
  {
    "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:

    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:

    [
  {
    "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:

    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:

    {
  "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. Append /petstorewalkthrough/pets so that it looks like this:

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

    Append the following header:

    Content-Type: application/json

    Add the following code to the request body:

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

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

    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:

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

You have reached the end of this walkthrough.

Map response payload

In this walkthrough, we show how to use models and mapping templates in API Gateway to transform the output of an API call from one data schema to another. This walkthrough builds on the instructions and concepts in the Getting started with API Gateway and the Map request parameters for an API Gateway API. If you have not yet completed those walkthroughs, we suggest you do them first.

This walkthrough uses API Gateway to get example data from a publicly accessible HTTP endpoint and from an Amazon Lambda function you create. Both the HTTP endpoint and the Lambda function return the same example data:

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

You will use models and mapping templates to transform this data to one or more output formats. In API Gateway, a model defines the format, also known as the schema or shape, of some data. In API Gateway, a mapping template is used to transform some data from one format to another. For more information, see Working with models and mapping templates.

The first model and mapping template is used to rename id to number, type to class, and price to salesPrice, as follows:

[
  {
    "number": 1,
    "class": "dog",
    "salesPrice": 249.99
  },
  {
    "number": 2,
    "class": "cat",
    "salesPrice": 124.99
  },
  {
    "number": 3,
    "class": "fish",
    "salesPrice": 0.99
  }
]

The second model and mapping template is used to combine id and type into description, and to rename price to askingPrice, as follows:

[
  {
    "description": "Item 1 is a dog.",
    "askingPrice": 249.99
  },
  {
    "description": "Item 2 is a cat.",
    "askingPrice": 124.99
  },
  {
    "description": "Item 3 is a fish.",
    "askingPrice": 0.99
  }
]

The third model and mapping template is used to combine id, type, and price into a set of listings, as follows:

{
  "listings": [
    "Item 1 is a dog. The asking price is 249.99.",
    "Item 2 is a cat. The asking price is 124.99.",
    "Item 3 is a fish. The asking price is 0.99."
  ]
}

Step 1: Create a Lambda function

You first need to create a Lambda function that returns the sample data for the Lambda custom integration.

To create the Lambda function.

  1. Open the Amazon Lambda console at https://console.amazonaws.cn/lambda/.

  2. Choose Create function.

  3. Choose Author from scratch.

  4. For Function Name, type GetPetsInfo.

  5. Choose Create function.

  6. Copy the following Lambda function and paste it into the code editor in the Lambda. Choose Deploy to update your function.

    console.log('Loading event');

export const handler = function(event, context, callback) {
  callback(null, 
    [{"id": 1, "type": "dog", "price": 249.99},
    {"id": 2, "type": "cat", "price": 124.99},
    {"id": 3, "type": "fish", "price": 0.99}]); // SUCCESS with message
};
    Tip

    In the preceding code, written in Node.js, console.log writes information to an Amazon CloudWatch log. event contains the input to the Lambda function. context contains calling context. callback returns the result. For more information about how to write Lambda function code, see the "Programming Model" section in Amazon Lambda: How it Works and the sample walkthroughs in the Amazon Lambda Developer Guide.

Step 2: Create models

In this step, you create four models. The first three models represent the data output formats for use with the HTTP endpoint. The last model represents the data input schema for use with the Lambda function.

To create the first output model

  1. Sign in to the API Gateway console at https://console.amazonaws.cn/apigateway.

  2. If MyDemoAPI is displayed, choose Models.

  3. Choose Create.

  4. For Model name, type PetsModelNoFlatten.

  5. For Content type, type application/json.

  6. For Model description, type Changes id to number, type to class, and price to salesPrice.

  7. For Model schema, type the following JSON Schema-compatible definition:

    {
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "PetsModelNoFlatten",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "number": { "type": "integer" },
      "class": { "type": "string" },
      "salesPrice": { "type": "number" }
    }
  }
}

  8. Choose Create model.

To create the second output model

  1. Choose Create.

  2. For Model name, type PetsModelFlattenSome.

  3. For Content type, type application/json.

  4. For Model description, type Combines id and type into description, and changes price to askingPrice.

  5. For Model schema, type the following:

    {
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "PetsModelFlattenSome",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "description": { "type": "string" },
      "askingPrice": { "type": "number" }    
    }
  }
}

  6. Choose Create model.

To create the third output model

  1. Choose Create.

  2. For Model name, type PetsModelFlattenAll.

  3. For Content type, type application/json.

  4. For Model description, type Combines id, type, and price into a set of listings.

  5. For Model schema, type the following:

    {
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "PetsModelFlattenAll",
  "type": "object",
  "properties": {
    "listings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

  6. Choose Create model.

To create the input model

  1. Choose Create.

  2. For Model name, type PetsLambdaModel.

  3. For Content type, type application/json.

  4. For Model description, type GetPetsInfo model.

  5. For Model schema, type the following:

    {
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "PetsLambdaModel",
  "type": "array",
  "items": {
    "type": "object", 
    "properties": {
      "id": { "type": "integer" },
      "type": { "type": "string" },
      "price": { "type": "number" }
    }
  }
}

  6. Choose Create model.

Step 3: Create resources

In this step, you create four resources. The first three resources enable you to get the example data from the HTTP endpoint in the three output formats. The last resource enables you to get the example data from the Lambda function in the same output schema of /flattensome.

To create the first resource

  1. In the links list, choose Resources.

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

  3. For Resource Name, type NoFlatten.

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

To create the second resource

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

  2. For Resource Name, type FlattenSome.

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

To create the third resource

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

  2. For Resource Name, type FlattenAll.

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

To create the fourth resource

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

  2. For Resource Name, type LambdaFlattenSome.

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

Step 4: Create GET methods

In this step, you create a GET method for each of the resources you created in the previous step.

To create the first GET method

  1. In the Resources list, choose /petstorewalkthrough/flattenall, and then choose Create Method.

  2. From the drop-down list, choose GET, and then choose the check mark icon to save your choice.

  3. In the Setup pane, choose HTTP for the Integration type and GET for HTTP method, type http://petstore-demo-endpoint.execute-api.com/petstore/pets in Endpoint URL, and choose Save.

To create the second GET method

  1. In the Resources list, choose /petstorewalkthrough/lambdaflattensome, and then choose Create Method.

  2. From the drop-down list, choose GET, and then choose the check mark to save your choice.

  3. In the Setup pane, choose Lambda Function for the Integration type.

  4. Leave the Use Lambda Proxy Integration box unchecked.

  5. Enter GetPetsInfo for the Lambda function.

  6. Choose OK when prompted to add permission to the Lambda function.

To create the third GET method

  1. In the Resources list, choose /petstorewalkthrough/flattensome, and then choose Create Method.

  2. From the drop-down list, choose GET, and then choose the check mark icon to save your choice.

  3. In the Setup pane, choose HTTP for the Integration type and GET for HTTP method, type http://petstore-demo-endpoint.execute-api.com/petstore/pets in Endpoint URL, and then choose Save.

To create the fourth GET method

  1. In the Resources list, choose /petstorewalkthrough/noflatten, and then choose Actions, Create Method.

  2. From the drop-down list, choose GET, and then choose the check mark icon to save your choice.

  3. In the Setup pane, choose HTTP for the Integration type and GET for HTTP method, type http://petstore-demo-endpoint.execute-api.com/petstore/pets in Endpoint URL, and then choose Save.

Step 5: Set up and test the methods

In this step, you configure the method responses, integration requests, and integration responses to specify the input and output data schemas (or models) for the GET methods associated with the HTTP endpoint and the Lambda function. You also learn to test calling these methods using the API Gateway console.

To set up the integration for the first GET method and then test it

  1. From the API's Resources tree, choose GET under the /petstorewalkthrough/flattenall node.

  2. In the Method Execution pane, choose Method Response, and then choose the arrow next to 200.

  3. In the Response Models for 200 area, for application/json, choose the pencil icon to start setting up the model for the method output. For Models, choose PetsModelFlattenAll, and then choose the check mark icon to save the setting.

  4. Choose Method Execution, choose Integration Response, and then choose the arrow next to 200.

  5. Expand the Mapping Templates section, choose application/json under Content-Type.

  6. For Generate template from model, choose PetsModelFlattenAll to display a mapping template after the PetsModelFlattenAll model as a starting point.

  7. Modify the mapping template code as follows:

    #set($inputRoot = $input.path('$'))
{
  "listings" : [
#foreach($elem in $inputRoot)
    "Item number $elem.id is a $elem.type. The asking price is $elem.price."#if($foreach.hasNext),#end
        
#end
  ]
}

  8. Choose Save.

  9. Choose Method Execution, and in the Client box, choose TEST, and then choose Test. If successful, Response Body displays the following:

    {
  "listings" : [
    "Item number 1 is a dog. The asking price is 249.99.",        
    "Item number 2 is a cat. The asking price is 124.99.",        
    "Item number 3 is a fish. The asking price is 0.99."        
  ]
}
To set up integration for the second GET method and then test it

  1. From the API's Resources tree, choose GET under the /petstorewalkthrough/lambdaflattensome node.

  2. In Method Execution, choose Method Response. And then choose the arrow next to 200 to expand the section.

  3. In the Response Models for 200 area, choose the pencil icon on the row for the content type of application/json. Choose PetsModelFlattenSome for Models, and then choose the check mark icon to save the choice.

  4. Go back to Method Execution. Choose Integration Response, and then choose the arrow next to 200.

  5. In the Mapping Templates section, choose application/json under Content-Type.

  6. For Generate template, choose PetsModelFlattenSome to display the mapping script template for the output of this method.

  7. Modify the code as follows, and then choose Save:

    #set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
  {
    "description" : "Item $elem.id is a $elem.type.",
    "askingPrice" : $elem.price
  }#if($foreach.hasNext),#end

#end
]

  8. Choose Method Execution, and in the Client box, choose TEST, and then choose Test. If successful, Response Body displays the following:

    [
  {
    "description" : "Item 1 is a dog.",
    "askingPrice" : 249.99
  },    
  {
    "description" : "Item 2 is a cat.",
    "askingPrice" : 124.99
  },    
  {
    "description" : "Item 3 is a fish.",
    "askingPrice" : 0.99
  }    
]
To set up integration for the third GET method and then test it

  1. From the API's Resources tree, choose GET under the /petstorewalkthrough/flattensome node.

  2. In the Method Execution pane, choose Method Response.

  3. Choose the arrow next to 200.

  4. In the Response Models for 200 area, for application/json, choose the pencil icon. For Models, choose PetsModelFlattenSome, and then choose the check-mark icon to save the choice.

  5. Go back to Method Execution and choose Integration Response.

  6. Choose the arrow next to 200 to expand the section.

  7. Expand the Mapping Templates area. Choose application/json for Content-Type. For Generate template, choose PetsModelFlattenSome to display a mapping script template for the output of this method.

  8. Modify the code as follows:

    #set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
  {
    "description": "Item $elem.id is a $elem.type.",
    "askingPrice": $elem.price 
  }#if($foreach.hasNext),#end

#end
]

  9. Choose Save.

  10. Go back to Method Execution and choose TEST in the Client box. And then choose Test. If successful, Response Body displays the following:

    [
  {
    "description": "Item 1 is a dog.",
    "askingPrice": 249.99
  },    
  {
    "description": "Item 2 is a cat.",
    "askingPrice": 124.99
  },    
  {
    "description": "Item 3 is a fish.",
    "askingPrice": 0.99
  }    
]
To set up integration for the fourth GET method and then test it

  1. From the API's Resources tree, choose GET under the /petstorewalkthrough/noflatten node.

  2. In the Method Execution pane, choose Method Response, and then expand the 200 section.

  3. In the Response Models for 200 area, for application/json, choose the pencil icon to update the response model for this method.

  4. Choose PetsModelNoFlatten as the model for the content type of application/json, and then choose the check-mark icon to save the choice.

  5. Choose Method Execution, choose Integration Response, and then choose the arrow next to 200 to expand the section.

  6. Expand the Mapping Templates section. Choose application/json for Content-Type. For Generate templates, choose PetsModelNoFlatten to display a mapping script template for the output of this method.

  7. Modify the code as follows:

    #set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
  {
    "number": $elem.id,
    "class": "$elem.type",
    "salesPrice": $elem.price 
  }#if($foreach.hasNext),#end

#end
]

  8. Choose Save.

  9. Go back to Method Execution, and in the Client box, choose TEST, and then choose Test. If successful, Response Body displays the following:

    [
  {
    "number": 1,
    "class": "dog",
    "salesPrice": 249.99
  },    
  {
    "number": 2,
    "class": "cat",
    "salesPrice": 124.99
  },    
  {
    "number": 3,
    "class": "fish",
    "salesPrice": 0.99
  }    
]

Step 6: Deploy the API

In this step, you 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.

  3. For Deployment description, type Using models and mapping templates walkthrough.

  4. Choose Deploy.

Step 7: Test the API

In this step, you go outside of the API Gateway console to interact with both the HTTP endpoint and the Lambda function.

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

    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/noflatten so that it looks like this:

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

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

    [
  {
    "number": 1,
    "class": "dog",
    "salesPrice": 249.99
  },    
  {
    "number": 2,
    "class": "cat",
    "salesPrice": 124.99
  },    
  {
    "number": 3,
    "class": "fish",
    "salesPrice": 0.99
  }    
]

  4. After petstorewalkthrough/, replace noflatten with flattensome.

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

    [
  {
    "description": "Item 1 is a dog.",
    "askingPrice": 249.99
  },    
  {
    "description": "Item 2 is a cat.",
    "askingPrice": 124.99
  },    
  {
    "description": "Item 3 is a fish.",
    "askingPrice": 0.99
  }    
]

  6. After petstorewalkthrough/, replace flattensome with flattenall.

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

    {
  "listings" : [
    "Item number 1 is a dog. The asking price is 249.99.",        
    "Item number 2 is a cat. The asking price is 124.99.",        
    "Item number 3 is a fish. The asking price is 0.99."        
  ]
}

  8. After petstorewalkthrough/, replace flattenall with lambdaflattensome.

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

    [
  {
    "description" : "Item 1 is a dog.",
    "askingPrice" : 249.99
  },    
  {
    "description" : "Item 2 is a cat.",
    "askingPrice" : 124.99
  },    
  {
    "description" : "Item 3 is a fish.",
    "askingPrice" : 0.99
  }    
]

Step 8: Clean up

If you no longer need the Lambda function you created for this walkthrough, you can delete it now. You can also delete the accompanying IAM resources.

Warning

If you delete a Lambda function your APIs rely on, those APIs will no longer work. Deleting a Lambda function cannot be undone. If you want to use the Lambda function again, you must re-create the function.

If you delete an IAM resource a Lambda function relies on, the Lambda function and any APIs that rely on it will no longer work. Deleting an IAM resource cannot be undone. If you want to use the IAM resource again, you must re-create the resource. If you plan to continue experimenting with the resources you created for this and the other walkthroughs, do not delete the Lambda invocation role or the Lambda execution role.

To delete the Lambda function

  1. Sign in to the Amazon Web Services Management Console and open the Amazon Lambda console at https://console.amazonaws.cn/lambda/.

  2. On the Lambda: Function list page, in the list of functions, choose the button next to GetPetsInfo, and then choose Actions, Delete. When prompted, choose Delete again.

To delete the associated IAM resources

  1. Open the IAM console at https://console.amazonaws.cn/iam/.

  2. In the Details area, choose Roles.

  3. Select APIGatewayLambdaExecRole, and then choose Role Actions, Delete Role. When prompted, choose Yes, Delete.

  4. In the Details area, choose Policies.

  5. Select APIGatewayLambdaExecPolicy, and then choose Policy Actions, Delete. When prompted, choose Delete.

You have now reached the end of this walkthrough.