How do I associate a data model with my REST API in API Gateway?

Resolution

To associate a data model with a REST API in API Gateway, complete the following steps.

Write a model schema to associate with your REST API

Note: API Gateway models must use JSON schema draft 4. For information on how to write a model schema, see Data models for REST APIs.

Example model schema

This example model uses application/json as the default key to select the mapping template. Your schema must adhere to the following conditions:

• API users must pass their UserID and Name values in the request body.
• The values for UserID and Name must be string values.
• The value for Age must be an integer value of 18 or greater.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User",
  "type": "object",
  "properties": {
    "UserID": {
      "type": "string"
    },
    "Name": {
      "type": "string"
    },
    "Age": {
      "description": "Age in years",
      "type": "integer",
      "minimum": 18
    }
  },
  "required": [
    "UserID",
    "Name"
  ]
}

Create a model for your REST API

To create a model in API Gateway, see Set up basic request validation in API Gateway.

Associate your model with the API method

Complete the following steps:

1. Open your API in the API Gateway console.
2. From the navigation pane, choose Resources.
3. Select the API method that you want to associate the model with.
4. In the Method Execution pane, choose Method Request.
5. For Request Validator, select Validate body. Then, choose the check icon to save your selection.
6. Expand Request Body. Then, choose Add model.
7. For Content type, enter the content type of your model. For example, enter application/json.
8. For Model name, select the model that you created.
9. Choose the check icon to save your selections.

Test the model

Complete the following steps:

1. From the Resources list of your API, choose the API method that you associated your model with.

2. In the Method Execution pane, choose TEST.

3. For Request Body, enter a request body that matches the model schema that you created.
   Note: To test the application/json example model, use the following example request body:

   { "UserID": "abc123", "Name": "Ana", "Age": 21}

4. Choose Test.

5. If the test response is successful, then the request body that's returned matches the model schema.

(Optional) Create a mapping template for the model

You can use a mapping template to modify requests that get sent to the integrated backend of your API. To create a mapping template, complete the following steps:

1. From the Resources list of your API, choose the API method that you associated your model with.

2. In the Method Execution pane, choose Integration Request.

3. Expand Mapping Templates.

4. For Request body passthrough, select When there are no templates defined (recommended).

5. Choose Add mapping template.

6. For Content-Type, enter the content type of your model. For example, enter application/json.

7. Choose the check icon to save your selection.

8. For Generate template, select the model that you created. For example, the application/json example model appears as the following:

   #set($inputRoot = $input.path('$')) { "UserID" : "$inputRoot.UserID", "Name" : "$inputRoot.Name", "Age" : $inputRoot.Age }

9. Modify the preceding template so that it contains the values that you want to pass to the integrated backend of your API.

10. Choose Save.

Deploy your REST API to commit the changes

Complete the following steps:

1. From the navigation pane, choose Resources.
2. Choose Actions. Then, select Deploy API.
3. For Deployment stage, select a stage that already exists, or choose [New Stage] to create a stage.
   Important: If you create a new stage, then you must enter a name for Stage name.
4. Choose Deploy to receive the invoke URL that you use to make requests to your deployed API.
5. Copy the invoke URL.

Test your REST API

Send a test request to your API that uses the method and the content type associated with your model. A successful request returns a 200 OK response. An unsuccessful request returns a 400 status code.

To send a test request, use either an API development tool or a curl command. For more information about REST API calls in API Gateway, see Invoke REST APIs in API Gateway. For more information about the curl command, see the curl website.

Example curl command that uses the POST HTTP method request and tests for a 200 OK response

Note: This example command sends a test request to the example application/json model. The command returns a 200 OK response.

curl -X POST <API URL> -H 'Content-Type: application/json' -d '{ "UserID": "abc123", "Name": "Ana", "Age": 21 }'

(Optional) Example curl command that uses the POST HTTP method request and tests for a 400 status code

Note: The request body in this example command isn't valid, because it doesn't include the required model attribute UserID. The command returns a 400 status code.

curl -X POST <API URL> -H 'Content-Type: application/json' -d '{ "Name": "Ana", "Age": 21 }'