Hello again and welcome back,

API Gateway is my favourite service offered by AWS, it enabled me to build a RESTful API without ever having any real web-development experience. If you want a broader guide to everything API Gateway I suggest you head on over to the official docs

Today’s guide will detail how to get started with API Gateways, Request Mapping Models or (JSON Schema Models). I personally found the official documentation and guides a little “wanting” from a beginners walkthrough point of view, so decided to make a guide that walks through the basic elements needed to get started.

While I was building a serverless API for a local charity I volunteer for, I was writing a lot of boiler-plate code, (due to our architectural decisions, to keep each lambda functions code bundle separate), code that needed to be updated many times over, often manually. One day I came across the guide for API Gateway Mapping Models they seemed to be an ideal solution, I could remove all my codebased body payload validation and replace it with one mapping template, where it can be assigned to many lambda functions without changing any code!

Mapping Models are JSON Schema Models. I’ve created an example JSON schema to showcase the main functionality you need to get started (IMHO), objects, arrays and properties.

{
    "type": "array",
    "items": 
    {
        "type" : "object",
        "required": ["clinic", "name"],
        "properties" : 
        {
            "clinic" : { "type" : "string"},
            "name" : { "type" : "string"},
            "number" : { "type" : ["string", "number", "null"]},
            "postcode" : { "type" : ["string", "number", "null"]}      
        }
    }
}

Breaking down the example above into its core functions:

The JSON payload must be an array.

{
    "type": "array",
    "items": 
    {
        ...

    }
}

The array must be made up of objects.

        "type" : "object",
        "required": [...],
        "properties" : 
        {
           ...    
        }

The objects must contain any parameters defined in the “required” parameter. In this case “clinic” and “name”.

        "required": ["clinic", "name"],

Parameters of the object, whose keys match the defined keys below must be of the “type” specified. The following specifies “clinic” and “name” must be a “string” (and can not be null). “number” or “postcode” can be of type [“string”, “number”, “null”]

        "properties" : 
        {
            "clinic" : { "type" : "string"},
            "name" : { "type" : "string"},
            "number" : { "type" : ["string", "number", "null"]},
            "postcode" : { "type" : ["string", "number", "null"]}    
        }

Now we know what we can define with a Model its time to create one. To create a Model, simply navigate to the Models section of your API (after signing in to the AWS Console of course), click the blue “Create” button, name the model appropriatley, for “Content type” enter “applicaton/json” and paste your JSON schema into the “Model schema” text field, you can see me creating my template below.

For the schema to be enforced on your API’s methods, the methods need to have body validation enabled for the request, and methods need to be assigned the correct model. To check these settings, select the method with which you want to apply the JSON schema model and click the Method Request section

Ensure that your settings are similar to the below.

Hopefully, you understand little more of basics of how to implement JSON schema payload verification using AWS’ API Gateways Request Mapping Models now. Moreover, hopefully, it saves you as much time as it did me :-)

Until next time.