3.9 Resource Linking and Embedding

In business applications, resources are related to each other. For example, a sales order resource has a relationship to a contact resource and to a list of order line resources. Order lines in turn are related to products, etc. 

SData provides a standard way of representing this information in feed entries. It provides two options:

• Linking: The entry contains links to related resources. The consumer can read these resources through separate GET requests.
• Embedding: The XML payload of the related resources is directly embedded into the resource entry.

The following subsections detail the two options.

Linking

Links should be included directly inside the payload, as the following example demonstrates:

<salesOrder 
  sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrders('43660')" 
  sdata:key="43660"
  sdata:uuid="44D446D4-5700-41cc-92FB-3BA0FF6017CC"
  xmlns="http://schemas.sage.com/myContract">
  <salesOrderID>43660</salesOrderID>
  <orderDate>2001-07-01</orderDate>
  <shipDate xsi:nil="true" />
  <contact 
    sdata:url="http://www.example.com/sdata/myApp/myContract/-/contacts('216')" 
    sdata:key="216" 
    sdata:uuid="4AB7DA77-C841-4bef-955A-08D661D86430"
    sdata:lookup="http://www.example.com/sdata/myApp/myContract/-/contacts" />
  <subTotal>7326.5034</subTotal>
  <orderLines 
    sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines?where=salesOrderID%20eq%2043660" /> 
</salesOrder>

SData provides five attributes to encode link information inside XML payloads:

Attribute	Value	Description
sdata:url	http://www.example.com/sdata/myApp/myContract/-/contacts('216')	URL of the resource feed or entry This attribute SHOULD be present on all relationship elements. It SHOULD also be present on the element that represents the primary resource (<salesOrder> element in the example above).
sdata:key	216	Primary key value for the resource. This attribute SHOULD be present if the relationship is flagged with sme:isCollection="false" in the schema. It SHOULD NOT be present if the relationship is flagged with sme:isCollection="true". This attribute SHOULD also be present on the element that represents the primary resource (<salesOrder> element in the example above).
sdata:uuid	4AB7DA77-C841-4bef-955A-08D661D86430	UUID for the resource. This attribute MUST be present if the resource kind is flagged with sme:hasUuid="true" in the schema and if  the relationship is flagged with sme:isCollection="false" in the schema. This attribute MUST also be present on the element that represents the primary resource if its resource kind is flagged with sme:hasUuid="true" in the schema (<salesOrder> element in the example above).
sdata:lookup	http://www.example.com/sdata/myApp/myContract/-/contacts	URL to obtain a list of resource candidates for the relationship. See Feed Rendering section. This element is OPTIONAL.
sdata:descriptor	John Doe	Short human readable string for the resource. See Query Payload Control section. This attribute is OPTIONAL. It SHOULD be included in the payload if the consumer requested the descriptors with an include=$descriptors query parameter.

SData version 0.9 used Atom <link> elements to carry the link information. This approach has been deprecated in version 1.0.

Embedding

Embedding is controlled by the include and select query parameter. See Query Parameters section. By default, when these parameters are not specified, SData only embeds the URLs of related resources in the payload. It does not embed the full XML representation of the related resources.  In our example, the sales orders were obtained by the following query:

GET /sdata/myApp/myContract/salesOrders

and the returned entries contained an XML payload like:

<salesOrder 
  sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrders('43660')" 
  sdata:key="43660"
  sdata:uuid="44D446D4-5700-41cc-92FB-3BA0FF6017CC"
  xmlns="http://schemas.sage.com/myContract">
  <salesOrderID>43660</salesOrderID>
  <orderDate>2001-07-01</orderDate>
  <shipDate xsi:nil="true" />
  <contact 
    sdata:url="http://www.example.com/sdata/myApp/myContract/-/contacts('216')" 
    sdata:key="216" 
    sdata:uuid="4AB7DA77-C841-4bef-955A-08D661D86430"
    sdata:lookup="http://www.example.com/sdata/myApp/myContract/-/contacts" />
  <subTotal>7326.5034</subTotal>
  <orderLines 
    sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines?where=salesOrderID%20eq%2043660" />
</salesOrder>

The consumer can request that the sales order lines be embedded in the XML payload of the returned entries by adding an include parameter to the query:

GET /sdata/myApp/myContract/-/salesOrders?include=orderLines

Then the XML payload contains the lines:

<salesOrder 
  sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrders('43660')" 
  sdata:key="43660"
  sdata:uuid="44D446D4-5700-41cc-92FB-3BA0FF6017CC"
  xmlns="http://schemas.sage.com/myContract">
  <salesOrderID>43660</salesOrderID>
  <orderDate>2001-07-01</orderDate>
  <shipDate xsi:nil="true" />
  <contact 
    sdata:url="http://www.example.com/sdata/myApp/myContract/-/contacts('216')" 
    sdata:key="216" 
    sdata:uuid="4AB7DA77-C841-4bef-955A-08D661D86430"
    sdata:lookup="http://www.example.com/sdata/myApp/myContract/-/contacts" />
  <subTotal>7326.5034</subTotal>
  <orderLines 
    sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines?where=salesOrderID%20eq%2043660" >
    <salesOrderLine
      sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines('43660-1')"
      sdata:key="43660-1"
      sdata:uuid="36B2ECF4-4309-4e62-9878-28DF60B78CFD" >
      <salesOrderID>43660</salesOrderID>
      <lineNumber>1</lineNumber>
      <product
        sdata:url="http://www.example.com/sdata/myApp/myContract/-/products('758')" 
        sdata:key="758"
        sdata:uuid="455BCC8A-A261-4cf0-A105-599995160C5A"/>
      <orderQty>1</orderQty>
      <unitPrice>874.7940</unitPrice>
    </salesOrderLine>
    <salesOrderLine
      sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines('43660-2')"
      sdata:key="43660-2"
      sdata:uuid="CEFE3F52-5529-46b9-A166-79EDFD2D0595" >
      <salesOrderID>43660</salesOrderID>
      <lineNumber>2</lineNumber>
      <product
        sdata:url="http://www.example.com/sdata/myApp/myContract/-/products('437')" 
        sdata:key="437"
        sdata:uuid="5C9C54FE-B18C-42a9-A0E9-9FEC4BC05C10"/>
      <orderQty>2</orderQty>
      <unitPrice>820.70</unitPrice>
    </salesOrderLine>
  </orderLines>
</salesOrder>

Embedding is interesting for performance and transaction control. When a consumer creates or updates a complex resource, such as sales order, it can embed subresources. This allows the provider to process the resource and its subresources in a single transaction.

SData providers MUST use the mechanisms described above to represent linked and embedded resources in feed entries.

---