In the first article we looked at what Delta Queries were and the use cases that it addresses.
Now we will look at the mechanics of doing a delta query call and what the requests and responses will look like.
As we mentioned at the start a typical OData collection that is delta query enabled returns the same content as the query would do if it were not the only difference is that at the end of the document there is a link element. Well actually we don't have to imagine, the latest Netweaver Gateway with Service Pack 7 has these services already installed to consume
For now we are going to assume however we have a TravelAgencies collection that is delta query enabled (TravelAgencies_DQ) and we have made the first GET so we have the data parsed and cached locally in for example HTML5 LocalStorage (or IndexDB).
The link element looks like the following:
<link rel="delta" href="TravelAgencies_DQ?!deltatoken='12313D220A3A1EE3AA8A133BE813AF0F_20140310123632'"/>
If we now make a call to the server with the delta token we will get back an empty feed which is what we expect since we have not modified anything in the collection.
What we can do now is create a new travel agency using the standard OData CRUD pattern of a POST request and we will get back a 201 created http response.
URL:
<my service root>/TravelAgencies_DQ
ACTION:
POST
HEADERS:
Content-Type: application/json
BODY:
{
"agencynum": "04051971",
"NAME": "Great Escapades",
"STREET": "10 Square Bristol",
"POSTCODE": "BS1 4NT",
"CITY": "Bristol",
"COUNTRY":"GB",
"TELEPHONE":"+44 117 3153966",
"URL": "
http://www.sap.com",
"LANGU": "E",
"CURRENCY": "GBP"
}
The response back is:
201 - created
Now comes the interesting part:
We do a query: <My server>/TravelAgencies_DQ?!deltatoken='12313D220A3A1EE3AA8A133BE813AF0F_20140310123632' and we get back the newly created entity only rather than the entire collection:
<feed
xmlns="http://www.w3.org/2005/Atom"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xml:base="<my service root>">
<id><my service root>/TravelAgencies_DQ</id>
<title type="text">TravelAgencies_DQ</title>
<updated>2014-03-10T13:00:10Z</updated>
<author>
<name/>
</author>
<link href="TravelAgencies_DQ" rel="self" title="TravelAgencies_DQ"/>
<entry>
<id><my service root>/TravelAgencies_DQ('04051971')</id>
<title type="text">TravelAgencies_DQ('04051971')</title>
<updated>2014-03-10T13:00:10Z</updated>
<category term="RMTSAMPLEFLIGHT.Travelagency_DQ" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/>
<link href="TravelAgencies_DQ('04051971')" rel="edit" title="Travelagency_DQ"/>
<content type="application/xml">
<m:properties
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices">
<d:agencynum>04051971</d:agencynum>
<d:NAME>Great Escapades</d:NAME>
<d:STREET>10 Square Bristol</d:STREET>
<d:POSTBOX></d:POSTBOX>
<d:POSTCODE>BS1 4NT</d:POSTCODE>
<d:CITY>Bristol</d:CITY>
<d:COUNTRY>GB</d:COUNTRY>
<d:REGION></d:REGION>
<d:TELEPHONE>+44 117 3153966</d:TELEPHONE>
<d:URL>http://www.sap.com</d:URL>
<d:LANGU>E</d:LANGU>
<d:CURRENCY>GBP</d:CURRENCY>
<d:mimeType>text/html</d:mimeType>
</m:properties>
</content>
</entry>
<link rel="delta" href="TravelAgencies_DQ?!deltatoken='12313D220A3A1EE3AA8A133BE813AF0F_20140310130010'"/>
</feed>
As can be seen above, we also have a new key, which we can then recognize as a new record in the local cache and add it to the cache as such.
Now finally calling the collection again with the delta token returned from the last query returns back an empty feed as expected since we have got all the changes already.
<feed
xmlns="http://www.w3.org/2005/Atom"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xml:base="<my service root>">
<id><my service root>/TravelAgencies_DQ</id>
<title type="text">TravelAgencies_DQ</title>
<updated>2014-03-10T13:09:01Z</updated>
<author>
<name/>
</author>
<link href="TravelAgencies_DQ" rel="self" title="TravelAgencies_DQ"/>
<link rel="delta" href="TravelAgencies_DQ?!deltatoken='12313D220A3A1EE3AA8A133BE813AF0F_20140310130901'"/>
</feed>
So this is how adding records is done in a delta query as well as showing how to create a record using just plain JSON which is far easier and clearer than with XML.
Of course building a synchronization system would be much more difficult if we did have a mechanism to support detecting deletes. Detecting inserts and updates in a system is a trivial problem but when delete is also required, that is more of a challenge.
