WS-Education

The University of Colorado is offering an course called CSCI 7818: Web Services, where the NewsGator API gets a mention on the links page for the class, and even gets mentioned in the class notes for lecture 17.

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.

Location, Location, Location

freitasm has a great post on FeedDemon, which is great to hear, but the interesting part from an API perspective was the following quote:

I've used Sharpreader for some time before installing the NGES. The problem was keeping tabs on all feeds (at times more than 500!) while using three different devices: a desktop, a tablet PC and a Windows Mobile Pocket PC.

The NGES solved the problem by adding Locations, and allowing me to have my feeds served through a web interface, Microsoft Exchange or a PDA-friendly web interface.

Developers are sometimes confused by NewsGator's concept of Locations, but Mauricio explains exactly what locations are intended for: dividing your subscriptions into subsets that are intended to be consumed by different applications. Mauricio's talking about NewsGator Enterprise Server, but NGES implements the same API as NewsGator Online.

When you create a location in NewsGator Online, there's a parameter called autoAddSubs. If you set autoAddSubs to true, that location gets automatically subscribed to the user's entire subscription list, and subsequent calls to AddSubscription add the new subscription to all locations where autoAddSubs is set to true. If you set autoAddSubs to false, then the new location is created with no subscriptions, and subsequent calls to AddSubscription don't affect this location's subscription list. You have to use the AddSubscription and RemoveSubscription calls on the Location endpoints to manipulate the subscription list for locations where autoAddSubs is set to false.