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

You can create a model for your API in API Gateway to define the data format of a payload. API Gateway models must use JSON schema draft 4.

Follow these steps to associate a model with your API:

1.    Write a model schema and create a model for your API.

2.    Associate the model to the API method.

3.    Test the model.

4.    (Optional) Create a mapping template for the model.

5.    Deploy and test the API.

Write a model schema and create a model for your API

Write a model schema that you want to associate with your API. The following example model requires that API users must pass their UserID and Name in the request body. The model also requires that the UserID and Name must be string values, and that any provided Age must be an integer value that is 18 or greater.

Note: This example uses application/json.

{
  "$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"]
}

After writing the model schema, create a model using the API Gateway console.

Associate the 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 view, 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 view, choose TEST.

3.    For Request Body, enter a request body that matches the model schema that you created.

Note: To test the applicaton/json example model, you can use this sample request body:

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

4.    Choose Test.

5.    If the sample request body matches the model schema, you receive a successful response.

(Optional) Create a mapping template for the model

If you want to create a mapping template to modify requests sent to the integrated backend of your API, follow these steps:

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

2.    In the Method Execution view, 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 applicaton/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 and test the API

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. If you created a new stage, you must also enter a name for Stage name.

4.     Choose Deploy.

To test your API, send a test request to your API that uses the method and the content type associated with your model. You can send a test request using either an API development tool or a curl command. This curl command sends a test request for the example application/json model:

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

After you send a test request that uses the correct method and content type, verify that you receive a successful "200 OK" response.

As another test, you can send a test request with an invalid response body. The following request body is invalid according to the example application/json model because it doesn't include the required attribute UserID:

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

After you send a test request that uses an invalid response body, verify that you receive a 400 error with a message similar to "Invalid Request Body."


Did this page help you? Yes | No

Back to the AWS Support Knowledge Center

Need help? Visit the AWS Support Center

Published: 2018-11-08