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


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.

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 by email.


Subscribe for free