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

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 the author of Amazon Web Services in Action. I work as a software engineer, and independent consultant focused on AWS and DevOps.

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

Hire me

New book: Rapid Docker on AWS

A rapid way to get your web application up and running on AWS. Made for web developers and DevOps engineers who want to dockerize their web applications and run their containers on Amazon Web Services. Prior knowledge of Docker and AWS is not required.

Buy now

Incident Management for Slack

Team up to solve incidents with our chatbot marbot. Never miss a critical alert. Escalate alerts from your AWS infrastructure among your team members. Strong integrations with all parts of your AWS infrastructure: CloudWatch, Elastic Beanstalk, RDS, EC2, ...

Try for free

Reference API Gateway Models in CloudFormation

Michael Wittig

New book: Rapid Docker on AWS

Further reading

Incident Management for Slack