7.4 Read on Property URL

SData supports read operations on property URLs. For example, the following read will return the contact of a sales order resource:

GET /sdata/myApp/myContract/-/salesOrders('43660')/contact

This read returns the following response:

200 OK
Content-Type: application/atom+xml; type=entry
ETag: gJaGtgHyuAwW6jMI4i0njA
 
<entry xmlns:sdata="http://schemas.sage.com/sdata/2008/1" 
       xmlns:http="http://schemas.sage.com/sdata/http/2008/1" 
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/sdata/myApp/myContract/-/contact('216')</id>
  <title>Contact 216</title>
  <updated>2008-03-31T13:46:45Z</updated>

  <link rel="self" type="application/atom+xml; type=entry" title="Refresh" 
        href="http://www.example.com/sdata/myApp/myContract/-/contact('216')" />
  <link rel="edit" type="application/atom+xml; type=entry" title="Edit" 
        href="http://www.example.com/sdata/myApp/myContract/-/contact('216')" />
  <link rel="http://schemas.sage.com/sdata/link-relations/schema" 
        type="application/xml" title="Schema" 
        href="http://www.example.com/sdata/myApp/myContract/-/contacts/$schema?version=5" />
  <link rel="http://schemas.sage.com/sdata/link-relations/template" 
        type="application/atom+xml; type=entry" title="Template" 
        href="http://www.example.com/sdata/myApp/myContract/-/contacts/$template" />
  <link rel="http://schemas.sage.com/sdata/link-relations/post" 
        type="application/atom+xml; type=entry" title="Post" 
        href="http://www.example.com/sdata/myApp/myContract/-/contacts" />
  <link rel="http://schemas.sage.com/sdata/link-relations/service" 
        type="application/atom+xml; type=feed" title="Service" 
        href="http://www.example.com/sdata/myApp/myContract/-/contacts/$service" />

  <category scheme="http://schemas.sage.com/sdata/categories" 
            term="resource" label="Resource"/>

  <content>John Smith</content>
  <sdata:payload>
    <contact xmlns="http://schemas.sage.com/myContract"
      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">
      <firstName>John</firstName>
      <lastName>Doe</lastName>
      <email>john.doe@acme.com</email>
    </contact>
  </sdata:payload>
  <http:etag>gJaGtgHyuAwW6jMI4i0njA==</http:etag>
</entry>

This feature is restricted to properties that represent relationships (properties that carry an sme:relationship attribute in the schema).

Relationship properties that support this feature MUST be flagged with canGet=”true” in the schema.

SData uses the sme:isCollection attribute of the property to decide whether a GET operations on a property URL is a query that returns a feed or a read that returns a single entry. In the example, the contact property has sme:isCollection set to false and the GET operation returns an entry. In the Queries on Property URLs example, the orderLines property sme:isCollection is set to true and the GET operation returns a feed.

The fact that this read is performed on a property URL (salesOrders(‘43660’)/contact) rather than a resource URL (contacts(‘216’)) does not make any difference. All the mechanisms described in this section (caching, payload control) also apply to property URLs.

As contacts are exposed as a discrete resource kind, the id of the returned entry is its primary id contacts(‘216’), not the hierarchical URL that was submitted (salesOrders(‘43660’)/contact). This set up is recommended when the related resources are exposed as a separate resource kind and have such a primary URL. The other form (hierarchical URL) is allowed when the related resources don’t have a primary URL (when their resource kind is flagged as sme:canGet=”false”).

SData providers SHOULD support read operations on property URLs. They MUST support them on all the properties that are flagged with sme:canGet="true" and sme:isCollection="false" in the schema.