Additional Resources

📘 json-schema.org

📘 json-schema.org: Understanding JSON Schema

Intro

Models in API Gateway are a schema for data that we can use to compare our HTTP requests against. They are useful for validating the data coming into and out of your API.

The models are written in a JSON specification called JSON Schema (see links above).

We are creating a dummy application that will compare various pieces of data that users submit such as age, height & income.

Creating A Model

We will start by creating a new model in API Gateway

CompareData.json

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "CompareData",
    "type": "object",
    "properties": {
        "age": {"type": "integer"},
        "height": {"type": "integer"},
        "income": {"type": "integer"}
    },
    "required": ["age", "height", "income"]
}

⚠️ Object keys in models are Case Sensitive. If you use age in the model, a request with Age will not validate.

We can see that this model is very simple. We just have a couple of required headers, and then we list the data type for our various pieces of data. Right now they are all numbers, although later we may add some strings and booleans.

Then we list off which pieces of the data we require for the request to validate against the model. Which right now is all three of them.

Using A Model

Now that we have our first model, we need to attach it to a resource method. Let's start by going into the Method Request of our post method and adding the model there.

We then need to indicate that we would like to validate incoming requests.

Currently we just want to validate the body of the request.

Validation Behavior

There are some important things to note about validation behavior. To start with the property keys in the model are case sensitive, so age, height & income must match exactly. Not Age, Height & Income.

Secondly the way we have the model set up right now, we are just listing things that are required, meaning that the request will be rejected if we don't include all three of those items. However the model will not be rejected if there are additional items in the request.

This behavior could of course be modified by changing the model.

Update Mapping Template

Now that we have used a model to validate the body of our HTTP request in the Method Request section, we can head back over to the Integration Request > Mapping Templates section, and there AWS will have an auto-generated template for us with the name of the Model we created.

Although we obviously don't want 42 to be the value of everything that we send to Lambda, so we need to replace that with the value we want. Kudos to Amazon for the Hitchhikers reference though.

Instead we map these keys to the input like so.

mapping_template

#set($inputRoot = $input.path('$'))
{
  "age" : $inputRoot.age,
  "height" : $inputRoot.height,
  "income" : $inputRoot.income
}

If you are unfamiliar with the concept of mapping templates we introduced that here:

Ncoughlin: AWS API Gateway Request Data > Body Mapping Templates

This auto-generated template also works in the Integration Response section.

Automated Amazon Reports

Automatically download Amazon Seller and Advertising reports to a private database. View beautiful, on demand, exportable performance reports.

bidbear.io