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

Cover of Amazon Web Services in Action

Level up, strengthen your AWS skills.

Our book Amazon Web Services in Action is a comprehensive introduction to computing, storing, and networking in the AWS cloud. You'll find clear, relevant coverage of all the essential AWS services, emphasizing best practices for security, high availability, and scalability. Get the first chapter for free!

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

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

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

Briefcase icon
Hire me