cloudonaut
Blog Podcast Books & Videos Free Resources
Subscribe Podcast

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

Tags: aws cloudformation api-gateway
Michael Wittig

Michael Wittig

Consultant. Entrepreneur. Author. Focusing on Amazon Web Services (AWS) since 2013.

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

Briefcase icon
Work with me
Cover of Rapid Docker on AWS

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 icon
Buy now

Further reading

Marbot Logo

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

Slack icon
Try for free
Docker on AWS is ready for prime time
It was never more convenient to run Docker workloads on AWS. Our new book teaches you Docker, AWS, and CI/CD. Prior knowledge of Docker and AWS is not required.
Learn more!