6.8 Query on Property URL

SData supports queries on property URLs. For example, the following query will return the lines of a sales order resource:

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

This query returns the following response:

200 OK
Content-Type: application/atom+xml; type=feed

<feed xmlns:sdata="http://schemas.sage.com/sdata/2008/1" 
      xmlns:http="http://schemas.sage.com/sdata/http/2008/1" 
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:sle="http://www.microsoft.com/schemas/rss/core/2005" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns="http://www.w3.org/2005/Atom">

  <!-- Atom feed elements -->
  <title>Sage App | Order lines for order 43660</title>
  <id>http://www.example.com/sdata/myApp/myContract/-/salesOrders('43660')/orderLines</id>
  <updated>2008-03-31T13:46:45Z</updated>

  <!-- Feed level links -->
  <link rel="self" type="application/atom+xml; type=feed" title="Refresh" 
        href="http://www.example.com/sdata/myApp/myContract/-/salesOrders('43660')/orderLines" />
  <link rel="first" type="application/atom+xml; type=feed" title="FirstPage" 
        href="http://www.example.com/sdata/myApp/myContract/-/salesOrders('43660')/orderLines" />
  <link rel="last" type="application/atom+xml; type=feed" title="LastPage" 
        href="http://example.com/sdata/myApp/myContract/-/salesOrders('43660')/orderLines" />
  <link rel="http://schemas.sage.com/sdata/link-relations/schema" 
        type="application/xml" title="Schema" 
        href="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines/$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/-/salesOrderLines/$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/-/salesOrderLines" />
  <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/-/salesOrderLines/$service" />

  <!-- Categories -->
  <category scheme="http://schemas.sage.com/sdata/categories" 
            term="collection" label="Resource Collection"/>

  <!-- Paging information -->
  <opensearch:totalResults>2</opensearch:totalResults>
  <opensearch:startIndex>1</opensearch:startIndex>
  <opensearch:itemsPerPage>10</opensearch:itemsPerPage>

  <!-- Simple List Extensions (skipped for clarity) -->

  <!-- Atom entry -->
  <entry>
    <id>http://www.example.com/sdata/myApp/myContract/-/salesOrderLines('43660-1')</id>
    <title>Sales Order Line 43660-1</title>
    <updated>2008-03-31T13:46:45Z</updated>

    <link rel="self" type="application/atom+xml; type=entry" title="self" 
          href="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines('43660-1')" />

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

    <content>Sales order line 43660-1</content>

    <!-- Resource payload -->
    <sdata:payload>
      <salesOrderLine
        sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines('43660-1')"
        sdata:key="43660-1"
        sdata:uuid="36B2ECF4-4309-4e62-9878-28DF60B78CFD" >
        <orderNumber>43660</orderNumber>
        <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>
    </sdata:payload>
    <http:etag>gJaGtgHyuAwW6jMI4i0njA==</http:etag>
  </entry>

  <!-- Atom entry -->
  <entry>
    <id>http://www.example.com/sdata/myApp/myContract/-/salesOrderLines('43660-2')</id>
    <title>Sales Order Line 43660-2</title>
    <updated>2008-03-31T13:46:45Z</updated>

    <link rel="self" type="application/atom+xml; type=entry" title="self" 
          href="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines('43660-2')" />

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

    <content>Sales order line 43660-2</content>

    <!-- Resource payload -->
    <sdata:payload>
      <salesOrderLine
        sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines('43660-2')"
        sdata:key="43660-2"
        sdata:uuid="CEFE3F52-5529-46b9-A166-79EDFD2D0595" >
        <orderNumber>43660</orderNumber>
        <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>
    </sdata:payload>
    <http:etag>3nqPeQqoGoxQB5xf3NIijw==</http:etag>
  </entry>
</feed>

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.

The fact that this query is performed on a property URL (salesOrders(‘43660’)/orderLines) rather than a resource kind url (salesOrders), doesn’t make any difference. All the query mechanisms described in this section (filtering, sorting, paging, caching, etc.) also apply to property URLs.

One point to note is the way the entry ids are formed. In the example, we assumed that order lines are also exposed on their own, as a separate resource kind. The order line ids are not built as hierarchical URLs (something like salesOrders('43660')/orderLines('1') for the first line). Instead, they are built as primary URLs for order line resources (salesOrderLines('43660-1')). This URL set up is recommended when the subresources are exposed as a separate resource kind and have a primary URL. The other form (hierarchical URL) is allowed when the subresources don't have a primary URL (when their resource kind is flagged as sme:canGet="false").

Queries on property URLs return a feed when the property is flagged with sme:isCollection="true". On the other hand, when the property is flagged with sme:isCollection="false", the GET operation returns an entry rather than a feed. See Read on Property URL section for details.

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