Example data models and mapping templates for API Gateway - Amazon API Gateway

Example data models and mapping templates for API Gateway

The following sections provide examples of models and mapping templates that could be used as a starting point for your own APIs in API Gateway. For more information about data transformations, see Understanding mapping templates. For more information about data models, see Understanding data models.

Photo album example

The following example shows a photo album API in API Gateway. We provide an example data transformation, additional models, and mapping templates.

Example data transformation

The following example shows how you can transform input data about photos by using a Velocity Template Language (VTL) mapping template. For more information about the Velocity Template Language, see Apache Velocity - VTL Reference.

Input data
{ "photos": { "page": 1, "pages": "1234", "perpage": 100, "total": "123398", "photo": [ { "id": "12345678901", "owner": "23456789@A12", "photographer_first_name" : "Saanvi", "photographer_last_name" : "Sarkar", "secret": "abc123d456", "server": "1234", "farm": 1, "title": "Sample photo 1", "ispublic": true, "isfriend": false, "isfamily": false }, { "id": "23456789012", "owner": "34567890@B23", "photographer_first_name" : "Richard", "photographer_last_name" : "Roe", "secret": "bcd234e567", "server": "2345", "farm": 2, "title": "Sample photo 2", "ispublic": true, "isfriend": false, "isfamily": false } ] } }
Output mapping template
#set($inputRoot = $input.path('$')) { "photos": [ #foreach($elem in $inputRoot.photos.photo) { "id": "$elem.id", "photographedBy": "$elem.photographer_first_name $elem.photographer_last_name", "title": "$elem.title", "ispublic": $elem.ispublic, "isfriend": $elem.isfriend, "isfamily": $elem.isfamily }#if($foreach.hasNext),#end #end ] }
Output data
{ "photos": [ { "id": "12345678901", "photographedBy": "Saanvi Sarkar", "title": "Sample photo 1", "ispublic": true, "isfriend": false, "isfamily": false }, { "id": "23456789012", "photographedBy": "Richard Roe", "title": "Sample photo 2", "ispublic": true, "isfriend": false, "isfamily": false } ] }

Input model for photo data

You can define a model for your input data. This input model requires that you upload one photo, and it specifies a minimum of 10 photos for each page. You can use this input model to generate an SDK or to turn on a request validation for your API.

{ "$schema": "http://json-schema.org/draft-04/schema#", "title": "PhotosInputModel", "type": "object", "properties": { "photos": { "type": "object", "required" : [ "photo" ], "properties": { "page": { "type": "integer" }, "pages": { "type": "string" }, "perpage": { "type": "integer", "minimum" : 10 }, "total": { "type": "string" }, "photo": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "owner": { "type": "string" }, "photographer_first_name" : {"type" : "string"}, "photographer_last_name" : {"type" : "string"}, "secret": { "type": "string" }, "server": { "type": "string" }, "farm": { "type": "integer" }, "title": { "type": "string" }, "ispublic": { "type": "boolean" }, "isfriend": { "type": "boolean" }, "isfamily": { "type": "boolean" } } } } } } } }

Output model for photo data

You can define a model for your output data. You can use this model for a method response model, which is necessary when you generate a strongly typed SDK for the API. This causes the output to be cast into an appropriate class in Java or Objective-C.

{ "$schema": "http://json-schema.org/draft-04/schema#", "title": "PhotosOutputModel", "type": "object", "properties": { "photos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "photographedBy": { "type": "string" }, "title": { "type": "string" }, "ispublic": { "type": "boolean" }, "isfriend": { "type": "boolean" }, "isfamily": { "type": "boolean" } } } } } }

Input mapping template for photo data

You can define a mapping template to modify input data. You can modify input data for further function integration or integration responses.

#set($inputRoot = $input.path('$')) { "photos": { "page": $inputRoot.photos.page, "pages": "$inputRoot.photos.pages", "perpage": $inputRoot.photos.perpage, "total": "$inputRoot.photos.total", "photo": [ #foreach($elem in $inputRoot.photos.photo) { "id": "$elem.id", "owner": "$elem.owner", "photographer_first_name" : "$elem.photographer_first_name", "photographer_last_name" : "$elem.photographer_last_name", "secret": "$elem.secret", "server": "$elem.server", "farm": $elem.farm, "title": "$elem.title", "ispublic": $elem.ispublic, "isfriend": $elem.isfriend, "isfamily": $elem.isfamily }#if($foreach.hasNext),#end #end ] } }

News article example

The following example shows a news article API in API Gateway. We provide an example data transformation, additional models, and mapping templates.

Example data transformation

The following example shows how you can transform input data about a news article by using a Velocity Template Language (VTL) mapping template. For more information about the Velocity Template Language, see Apache Velocity - VTL Reference.

Input data
{ "count": 1, "items": [ { "last_updated_date": "2015-04-24", "expire_date": "2016-04-25", "author_first_name": "John", "description": "Sample Description", "creation_date": "2015-04-20", "title": "Sample Title", "allow_comment": true, "author": { "last_name": "Doe", "email": "johndoe@example.com", "first_name": "John" }, "body": "Sample Body", "publish_date": "2015-04-25", "version": "1", "author_last_name": "Doe", "parent_id": 2345678901, "article_url": "http://www.example.com/articles/3456789012" } ], "version": 1 }
Output mapping template
#set($inputRoot = $input.path('$')) { "count": $inputRoot.count, "items": [ #foreach($elem in $inputRoot.items) { "creation_date": "$elem.creation_date", "title": "$elem.title", "author": "$elem.author.first_name $elem.author.last_name", "body": "$elem.body", "publish_date": "$elem.publish_date", "article_url": "$elem.article_url" }#if($foreach.hasNext),#end #end ], "version": $inputRoot.version }
Output data
{ "count": 1, "items": [ { "creation_date": "2015-04-20", "title": "Sample Title", "author": "John Doe", "body": "Sample Body", "publish_date": "2015-04-25", "article_url": "http://www.example.com/articles/3456789012" } ], "version": 1 }

Input model for news data

You can define a model for your input data. This input model requires that a news article contains a URL, title, and body. You can use this input model to generate an SDK or to turn on a request validation for your API.

{ "$schema": "http://json-schema.org/draft-04/schema#", "title": "NewsArticleInputModel", "type": "object", "properties": { "count": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "required": [ "article_url", "title", "body" ], "properties": { "last_updated_date": { "type": "string" }, "expire_date": { "type": "string" }, "author_first_name": { "type": "string" }, "description": { "type": "string" }, "creation_date": { "type": "string" }, "title": { "type": "string" }, "allow_comment": { "type": "boolean" }, "author": { "type": "object", "properties": { "last_name": { "type": "string" }, "email": { "type": "string" }, "first_name": { "type": "string" } } }, "body": { "type": "string" }, "publish_date": { "type": "string" }, "version": { "type": "string" }, "author_last_name": { "type": "string" }, "parent_id": { "type": "integer" }, "article_url": { "type": "string" } } } }, "version": { "type": "integer" } } }

Output model for news data

You can define a model for your output data. You can use this model for a method response model, which is necessary when you generate a strongly typed SDK for the API. This causes the output to be cast into an appropriate class in Java or Objective-C.

{ "$schema": "http://json-schema.org/draft-04/schema#", "title": "PhotosOutputModel", "type": "object", "properties": { "photos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "photographedBy": { "type": "string" }, "title": { "type": "string" }, "ispublic": { "type": "boolean" }, "isfriend": { "type": "boolean" }, "isfamily": { "type": "boolean" } } } } } }

Input mapping template for news data

You can define a mapping template to modify input data. You can modify input data for further function integration or integration responses.

#set($inputRoot = $input.path('$')) { "count": $inputRoot.count, "items": [ #foreach($elem in $inputRoot.items) { "last_updated_date": "$elem.last_updated_date", "expire_date": "$elem.expire_date", "author_first_name": "$elem.author_first_name", "description": "$elem.description", "creation_date": "$elem.creation_date", "title": "$elem.title", "allow_comment": "$elem.allow_comment", "author": { "last_name": "$elem.author.last_name", "email": "$elem.author.email", "first_name": "$elem.author.first_name" }, "body": "$elem.body", "publish_date": "$elem.publish_date", "version": "$elem.version", "author_last_name": "$elem.author_last_name", "parent_id": $elem.parent_id, "article_url": "$elem.article_url" }#if($foreach.hasNext),#end #end ], "version": $inputRoot.version }