SData Specification

Previous Page Arrow Next Page Arrow

1.3 Linking Protocol

Linking URLs

SData provides a REST API to manipulate the linking information, i.e. the UUIDs of resources. Applications that support linking MUST expose URLs like the following:

http://www.example.com/sdata/myApp/myContract/-/accounts/$linked
http://www.example.com/sdata/myApp/myContract/-/accounts/$linked('138BB530-18CB-410d-8969-753F9EB8BC08')

The first URL represents the collection of all the account resources that are linked,. A GET request on this URL returns an atom feed that enumerates all the account resources that have a UUID assigned to them (with the usual SData paging mechanism). A POST on this URL assigns a new UUID to an existing resource.

The second URL represents a single linked resource. A GET request on this URL returns an atom entry containing the linked resource. A PUT request reassigns the UUID to a different resource. A DELETE request unlinks the resource by deleting its UUID association.

These URLs manipulate the linking metadata (correlations between UUIDs and internal IDs), not the resource itself. So, for example, a DELETE request on the second URL above only deletes the correlation. The resource itself is not deleted.

A provider supporting linking MUST expose a $linked URL as described above. The provider MUST support the GET/PUT/POST/DELETE operations on the said URL.

Reading a Single Linking Entry

A single linking entry can be read with a GET request like the following:

GET /sdata/myApp/myContract/-/accounts/$linked('138BB530-18CB-410d-8969-753F9EB8BC08') HTTP/1.1

A typical response will be:

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

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:sdata="http://schemas.sage.com/sdata/2008/1">
  <id>http://www.example.com/sdata/myApp/myContract/-/accounts/$linked('138BB530-18CB-410d-8969-753F9EB8BC08')</id>
  <title>Linked account 138BB530-18CB-410d-8969-753F9EB8BC08</title>
  <updated>2008-05-25T13:27:19.207Z</updated>
  <payload xmlns="http://schemas.sage.com/sdata/2008/1">
    <account sdata:uuid="138BB530-18CB-410d-8969-753F9EB8BC08"
      sdata:url="http://www.example.com/myApp/myContract/-/accounts('A0027')"
      sdata:key="A0027" 
      xmlns="http://schemas.sage.com/myContract">
      <name>ACME Inc.</name>
      <!-- more account data -->
    </account>
  </payload>
</entry>

The URL of the corresponding resource is obtained from the sdata:url attribute of the payload.

If the service consumer only needs to retrieve the URL, not the actual payload, it may do so by adding an empty selectparameter to its request:

GET /sdata/myApp/myContract/-/accounts/$linked('138BB530-18CB-410d-8969-753F9EB8BC08')?select= HTTP/1.1

Querying Feeds of Linking Entries

A consumer can also query the list of linked resources with a GET request on the $linked collection URL. Here is an example:

GET /sdata/myApp/myContract/-/accounts/$linked HTTP/1.1

This request retuns an SData feed with entries similar to the one above.

The provider MUST support the sequential and indexed paging mechanisms on this feed (see Query Paging section) so that consumers can handle large collections of links.

On the other hand, the provider does not need to support the other query parameters (where, orderBy, etc.) on $linkedURLs. If the consumer needs such features in his query, he should query the normal resource collection URL and test the presence of a UUID.

A provider supporting linking MUST support the sequential and indexed paging mechanism for GET operations on the $linked URL. The provider MAY additionally support additional query parameters for GET operations on the $linked URL.

Linking an existing resource

A consumer can link an existing resource, i.e., assign it a new UUID, by POSTing to the $linked collection URL. Here is an example:

POST /sdata/myApp/myContract/-/accounts/$linked HTTP/1.1
Content-Type: application/atom+xml; type=entry

<entry xmlns="http://www.w3.org/2005/Atom" >
  <id/>
  <title/>
  <updated>2008-05-25T13:27:19.207Z</updated>
  <payload xmlns="http://schemas.sage.com/sdata/2008/1">
    <account sdata:uuid="88815929-A503-4fcb-B5CC-F1BB8ECFC874"
      sdata:url="http://www.example.com/myApp/myContract/-/accounts('A0028')"
      xmlns="http://schemas.sage.com/myContract"/>
  </payload>
</entry>

This request will create the link. A typical successful response will be:

201 Created
Content-Type: application/atom+xml; type=entry
Location: http://www.example.com/sdata/myApp/myContract/-/accounts/$linked('88815929-A503-4fcb-B5CC-F1BB8ECFC874')
 
<entry xmlns="http://www.w3.org/2005/Atom" >
  <id>http://www.example.com/sdata/myApp/myContract/-/accounts/$linked('88815929-A503-4fcb-B5CC-F1BB8ECFC874')</id>
  <title>Linked account 88815929-A503-4fcb-B5CC-F1BB8ECFC874</title>
  <updated>2008-05-25T13:27:19.207Z</updated>
  <payload xmlns="http://schemas.sage.com/sdata/2008/1">
    <account sdata:uuid="88815929-A503-4fcb-B5CC-F1BB8ECFC874"
      sdata:url="http://www.example.com/myApp/myContract/-/accounts('A0028')"
      sdata:key="A0028" 
      xmlns="http://schemas.sage.com/myContract">
      <name>Hammers Inc.</name>
      <!-- more account data -->
    </account>
  </payload>
</entry>

In the example above, the UUID is provided by the consumer (sdata:uuid attribute in the posted entry). It is also possible to let the provider generate and assign the UUID. This can be achieved by removing the sdata:uuid attribute from the posted entry.

On the other hand, the consumer MUST provide an sdata:url attribute that references an existing resource.

A provider supporting linking MUST support the creation of a linking entry to a previously unlinked resource. This is achieved by the POST operation on the $linked URL.

If the payload contains a sdata:uuid attribute, the provider MUST assign the content of the attribute as the UUID for the resource. If the payload does not contain the sdata:uuid attribute, the provider MUST generate and assign a UUID for the resource.

A provider SHOULD accept a POST operation on a resource that is already linked if the sdata:uuid attribute is not specified in the operation’s payload or if it present and matches the current sdata:uuid of the resource.

However, a provider MUST reject a POST request targeting an already linked resource if the operation’s payload contains the sdata:uuid attribute and its value does not match the existing UUID for the resource.

The provider MUST provide the sdata:uuid attribute in the response. Its value MUST identify the resource targeted by the POST operation.

The initiator of the POST request on the $linked URL MUST provide the sdata:url attribute with its request payload.

Reassiging a UUID

A consumer can reassign a UUID to a different resource with a PUT request on the $linked URL. Here is an example of such a request:

PUT /sdata/myApp/myContract/-/accounts/$linked('88815929-A503-4fcb-B5CC-F1BB8ECFC874') HTTP/1.1
Content-Type: application/atom+xml; type=entry

<entry xmlns="http://www.w3.org/2005/Atom" >
  <id>http://www.example.com/sdata/myApp/myContract/-/accounts/$linked('88815929-A503-4fcb-B5CC-F1BB8ECFC874')</id>
  <title>Linked account 88815929-A503-4fcb-B5CC-F1BB8ECFC874</title>
  <updated>2008-05-25T13:27:19.207Z</updated>
  <payload xmlns="http://schemas.sage.com/sdata/2008/1">
    <account sdata:uuid="88815929-A503-4fcb-B5CC-F1BB8ECFC874"
      sdata:url="http://www.example.com/myApp/myContract/-/accounts('A0029')"
      xmlns="http://schemas.sage.com/myContract"/>
  </payload>
</entry>

This request changes the link so that the UUID points to account A0029 instead of A0028 before.

The response is the same as what a GET operation would return after the update.

 &lt;!– @page { margin: 2cm } P { margin-bottom: 0.21cm } –&gt;

A provider supporting linking MUST support the amendment of an existing linking entry.

Deleting a Linking Entry

A consumer can delete a link with a DELETE request. Here is an example:

DELETE /sdata/myApp/myContract/-/accounts/$linked('88815929-A503-4fcb-B5CC-F1BB8ECFC874') HTTP/1.1

A successful response will be:

200 OK

A provider supporting linking MUST support the deletion of an existing linking entry.

Security

Requests on the $linked URLs will be authenticated like normal SData requests. The link and sync framework may restrict operations that modify the linking metadata to special accounts, like the account that runs synchronization passes, to avoid accidental or malicious alteration of this data.

Providers SHOULD NOT use the ETag mechanism to better control concurrent modifications of linking entries. This feature seems unnecessary in this context because PUT operations are rather exceptional and the likelyhood of two concurrent PUT operations on the same entry seems very low.

Batching Linking Requests

A typical linking process is likely to create a large number of linking entries when correlating two applications that both have a large number of records. So, applications that support linking SHOULD also support the SData batching protocol on linked entries. The batching URL will be naturally constructed as:

http://www.example.com/sdata/myApp/myContract/-/accounts/$linked/$batch

The batch request will be similar to a normal SData batch request.

A provider supporting linking SHOULD support batching operations by means of the $linked/$batch URL.

Previous Page Arrow Next Page Arrow