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

Last updated: 2020-10-30

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

Short description

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.

Associate a model with your API by doing the following:

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

2.     Associating the model to the API method.

3.     Testing the model.

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

5.     Deploying and testing the API.

Resolution

Writing a model schema and create a model for your API

Write a model schema 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.

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

Testing 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 application/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) Creating 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 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.

Deploying and testing 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 article help?


Do you need billing or technical support?