Page History

...

Sub-resources are normally used for two reasons. First, when the type of data represented by the sub-resource is not merely a composite of the parent property. Second, and most importantly, when the data represented by the sub-resource is subject to being repeated. To illustrateRepeated data will often come from two sources: values from associated multivalue fields and rows from a database table.

To visualize sub-resources, let's reconsider revisit the final resource object used created in the What is a sub-property? article: 

{
   "mailing":{
      "address":"PO Box 1234",
      "city":"New Orleans",
      "county":"Orleans",
      "state":"LA",
      "zip":"70116"
   },
   "shipping":{
      "address":"6649 N Blue Gum St",
      "city":"New Orleans",
      "county":"Orleans",
      "state":"LA",
      "zip":"70116"
   }
}

This sample resource object uses sub-properties because it assumes the mailing and shipping parent properties are unique in the resource object, but they still require their own (albeit similar) composite properties. Perhaps Now what if we need a resource object that allows for to display any number of addresses. Perhaps we need a resource object that allows users ? What if users are allowed to define the type of addresses. address types? Either or both of these situations are perfect candidates for using sub-resources. Let's start by seeing how the above resource object would look using sub-resources:

...