Page History
...
A sub-resource is a resource, which means it can have properties, sub-properties, and be as complex as any resource. The critical difference is that sub-resources do not appear alone but rather as members of a parent property. This is similar to how sub-properties are displayed, but there can be more than one sub-resource belonging to a parent property. For this reason, sub-resources are contained within a JSON array.
Digging Deeper
...
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 illustrate, let's reconsider the final resource object used in the What is a sub-property? article:
Code Block | ||
---|---|---|
| ||
{
"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 used sub-properties because it was assumed that the mailing and shipping parent properties were unique but each one had their own (albeit similar) composite properties. Perhaps we need a resource object that allows for one to many addresses. Perhaps we need a resource object that allows users to define the type of addresses. Either or both of these situations are perfect candidates for using sub-resources. Let's start by redesign the above resource object with sub-resources instead of sub-properties:
Code Block | ||
---|---|---|
| ||
{
"addresses":[
{
"type":"Mailing",
"address":"PO Box 1234",
"city":"New Orleans",
"county":"Orleans",
"state":"LA",
"zip":"70116"
},
{
"type":"Shipping",
"address":"6649 N Blue Gum St",
"city":"New Orleans",
"county":"Orleans",
"state":"LA",
"zip":"70116"
}
]
} |