Reference API Gateway Models in CloudFormation

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


Subscribe to free monthly updates.

One subscriber wins our book AWS in Action every month.

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.

Is anything missing in my article? I'm looking forward to your feedback! @hellomichibye or michael@widdix.de.

marbot

Are you part of a highly motivated DevOps team? Use marbot, a friendly chatbot, to forward all kind of alerts from your AWS infrastructure to Slack. Alerts are escalated across your team automatically allowing you to focus on your daily work.

Amazon Web Services in Action

Amazon Web Services in Action introduces you to computing, storing, and networking in the AWS cloud.

Customer Reviews:

Subscribe to free monthly updates.

One subscriber wins our book AWS in Action every month.


Subscribe for free