Sync Tokens in the NewsGator API

The one facet of the NewsGator API that seems to confuse developers more than any other is the "sync token".  The sync token grew out of a desire to cut down on bandwidth and roundtrips to the NewsGator servers.  With a plain HTTP architecture, you have Conditional GET mechanisms (ETag and Last-Modified) which help alleviate bandwidth usage.  In a SOAP architecture, you don't have those mechanisms, so the sync token was created as a way to determine differentials.  Essentially, the sync token is a bookmark that NewsGator can use to The sync token has a few uses in the NewsGator API:

1. In GetSubscriptionList, the sync token determines the state of the unseen attribute - this attribute is marked "True" when the server determines the feed has new content that the client hasn't seen yet.  If you're using a sync token, your application needs to retrieve only those feeds where unseen is true - there's no point in retrieving the other feeds because your application has already seen the content in those feeds.  GetSubscriptionList returns a new sync token as part of the result.  GetUpdates works like GetSubscriptionList, but returns just a list of the feed IDs where Unseen = true.
2. In GetNews, the sync token also determines what content the client has seen.  If your application calls GetNews with the syncToken parameter set and the unreadOnly parameter set to True, the API will return only those posts the client hasn't yet seen.
3. In MarkFeedRead, you can pass a syncToken to indicate when you last synchronized.  If the feed contains items your application hasn't yet seen (e.g. calling GetNews with that sync token would return any items), those items will not be marked read.
4. In the UpdatePostMetadata call, the sync token is used to filter the post states that get returned.  The sync token indicates when you last did a sync, and the assumption is that the client already knows about states that were changed before the sync token was created, so the server doesn't need to return these.

There are a few things to note about using sync tokens:

1. The usual routine is to call GetSubscriptionList or GetUpdates, then GetNews for each feed where unseen="True".  You want to use the same sync token for all of these calls, then extract the new sync token out of the response to GetSubscriptionList / GetUpdates and save it for the next cycle.
2. Normally, you'd use the same sync token for GetSubscriptionList and GetNews, but if any of the calls to GetNews fails, you shouldn't update the sync token for that feed, otherwise you will miss content for that feed.