Reference API Gateway Models in CloudFormation

Michael Wittig – 02 Sep 2016

API Gateway Models are defined using JSON Schema. You can reference a Model inside another Model using the $ref field. If you are familiar with the OpenAPI Specification fka Swagger, you may have seen something like this:

{
  "$ref": "#/definitions/User"
}

To make model references work with API Gateway, you need to provide an absolute reference that is predefined by AWS: https://apigateway.amazonaws.com/restapis/$ApiId/models/$ModelName

cloudonaut plus

Staying ahead of the game with Amazon Web Services (AWS) is a challenge. Our weekly videos and online events provide independent insights into the world of cloud. Subscribe to cloudonaut plus to get access to our exclusive videos and online events.

Subscribe now!

Let’s translate this to a CloudFormation template:

{
  "AWSTemplateFormatVersion": "2010-09-09",
  "Description": "Lambda and API Gateway",
  "Resources": {
    "RestApi": {
      "Type": "AWS::ApiGateway::RestApi",
      [...]
    },
    "UserModel": {
      "Type": "AWS::ApiGateway::Model",
      "Properties": {
        "ContentType": "application/json",
        "Name": "User",
        "RestApiId": {"Ref": "RestApi"},
        "Schema": {
          "$schema": "http://json-schema.org/draft-04/schema#",
          "type": "object",
          "title": "User",
          "additionalProperties": false,
          "properties": {
            "uid": {
              "type": "string"
            },
            "email": {
              "type": "string"
            },
            "phone": {
              "type": "string"
            }
          },
          "required": ["uid", "email", "phone"]
        }
      }
    },
    "UsersModel": {
      "Type": "AWS::ApiGateway::Model",
      "Properties": {
        "ContentType": "application/json",
        "Name": "Users",
        "RestApiId": {"Ref": "RestApi"},
        "Schema": {
          "$schema": "http://json-schema.org/draft-04/schema#",
          "type": "array",
          "title": "Users",
          "items": {
            "$ref": {"Fn::Join": ["", ["https://apigateway.amazonaws.com/restapis/", {"Ref": "RestApi"}, "/models/", {"Ref": "UserModel"}]]}
          }
        }
      }
    },
    "RestApi": {
      "Type": "AWS::ApiGateway::RestApi",
      "Properties": {
        "Name": "API Gateway ToDo"
      }
    }
  }
}

That’s it. Now you can build sophisticated API Gateway models that reference each other in CloudFormation.

Published on 02 Sep 2016

Tags: aws cloudformation api-gateway

Michael Wittig

I'm an independent consultant, technical writer, and programming founder. All these activities have to do with AWS. I'm writing this blog and all other projects together with my brother Andreas.

In 2009, we joined the same company as software developers. Three years later, we were looking for a way to deploy our software—an online banking platform—in an agile way. We got excited about the possibilities in the cloud and the DevOps movement. It’s no wonder we ended up migrating the whole infrastructure of Tullius Walden Bank to AWS. This was a first in the finance industry, at least in Germany! Since 2015, we have accelerated the cloud journeys of startups, mid-sized companies, and enterprises. We have penned books like Amazon Web Services in Action and Rapid Docker on AWS, we regularly update our blog, and we are contributing to the Open Source community. Besides running a 2-headed consultancy, we are entrepreneurs building Software-as-a-Service products.

We are available for projects.

You can contact me via Email, Twitter, and LinkedIn.

Hire me

Reference API Gateway Models in CloudFormation

cloudonaut plus

Michael Wittig

Further reading