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

Last updated: 2021-11-17

I want to integrate a model with my REST API in Amazon API Gateway. How can I do that?

Resolution

Important: API Gateway models must use JSON schema draft 4.

Write a model schema to associate with your REST API

For information on how to write a model schema, see Working with models and mapping templates.

Example model schema

Note: This example model uses application/json as the default key to select the mapping template, and requires the following:
API users must pass their UserID and Name in the request body.
The UserID and Name must be string values.
Any provided Age must be an integer value that is 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

Follow the instructions in Create a model in API Gateway to create a model using the schema that you wrote.

Associate your model to the API method

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, "application/json").

8.    For Model name, select the model that you created.

9.    Choose the check icon to save your selections.

Test the model

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 returned request body matches the model schema, then the test response is successful.

(Optional) Create a mapping template for the model

Note: You can modify requests sent to the integrated backend of your API by creating a mapping template.

To create a mapping template, do the following:

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, "application/json"). Then, choose the check icon to save your selection.

7.     For Generate template, select the model that you created.

Note: The application/json example model appears as:

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

8.     Modify the template according to the values that you want to pass to the integrated backend of your API.

9.    Choose Save.

Deploy your REST API to commit the changes

1.    From the navigation pane, choose Resources.

2.    Choose Actions. Then, select Deploy API.

3.    For Deployment stage, select an existing stage or choose [New Stage] to create a stage.
Important: If you created a new stage, you must also enter a name for Stage name.

4.    Choose Deploy. The invoke URL for making requests to the deployed API appears.

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, see Invoking a REST API in Amazon API Gateway.

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 example 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}

Did this article help?


Do you need billing or technical support?