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.

Michael Wittig

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.

Briefcase icon
Hire 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
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
🎉 Rapid Docker on AWS out now
Learn to bundle your application into Docker containers and run them on AWS. Get the eBook or join the Online Seminar.