NewsGator REST API Documentation
Posted by Nick Harris on August 17, 2007
Permalink
| Comments (3)
| TrackBack (0)
A new version of the NewsGator REST API Documentation is available:
http://www.newsgator.com/ngs/api/NewsGatorRESTAPI.pdf
If you were frustrated with the previous version, take a look at this one. It's much better and contains a lot more documentation.
NewsGator API and RSS Extensions - Update
Posted by Nick Harris on May 8, 2007
Permalink
| Comments (0)
If you've used either GetNews or Feeds.aspx to download RSS from the NewsGator API, you may have noticed that some RSS extensions are not supported while some are.
Support for any and all RSS extensions is on our API roadmap, and as they get implemented we'll let you know. Today we loaded support for slash:comments and GeoRSS.
The NewsGator API now supports and returns the following RSS extensions:
Yahoo Media RSS - Example
iTunes RSS Tags - Example
Simple List Extensions - Example
GeoRSS - Example
slash:comments - Example
These extensions allow your applications to be even more feature rich. The NewsGator Screen Saver uses Media RSS for it's "Show Pictures Only" feature and the new FeedDemon 2.5 uses most of them for a bunch of cool new features. Check out Nick Bradbury's release notes.
Like I said, we're constantly evaluating new extensions and adding support for them. If you see something you would like added that's not there already, send an email to support@newsgator.com and let us know!
NewsGator API ClipItems Method
Posted by Nick Harris on May 4, 2007
Permalink
| Comments (4)
If you're using the newest version of the NewsGator Toolbar, hopefully you've noticed the new "Clip" feature that I built into it. It's a pretty cool feature that allows you to clip any webpage to your NewsGator clippings. You can then use your clippings to build your own link blog and link feed.
Since this method is pretty new, it's not in our online documentation yet, so I thought I would write about it and show some C# example code of how to use it.
I should note that this method is currently restricted by your API token so you don't have access to it... but if you want access, you can contact our Brian Kellner (NewsGator Director of Product Managment) for more details.
ClipItems lives on the PostItem.asmx endpoint. It's a pretty simple call to make on the client side since all the cool magic happens on the server.
The request signiture looks like this:
POST /ngws/svc/PostItem.asmx HTTP/1.1 Host: services.newsgator.com Content-Type: application/soap+xml; charset=utf-8 Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
<soap12:Header>
<NGImpersonate xmlns="http://services.newsgator.com/ngws/Impersonate">
<ImpersonateUser>string</ImpersonateUser>
</NGImpersonate>
<NGAPIToken xmlns="http://services.newsgator.com/ngws/svc/PostItem.asmx">
<Token>string</Token>
</NGAPIToken>
</soap12:Header>
<soap12:Body>
<ClipItems xmlns="http://services.newsgator.com/ngws/svc/PostItem.asmx">
<clipList>
<ClippedItem>
<PostId>string</PostId>
<Url>string</Url>
<Title>string</Title>
<FolderId>int</FolderId>
</ClippedItem>
<ClippedItem>
<PostId>string</PostId>
<Url>string</Url>
<Title>string</Title>
<FolderId>int</FolderId>
</ClippedItem>
</clipList>
</ClipItems>
</soap12:Body>
</soap12:Envelope>
In my use case, I don't pass in a PostId since I don't have one. I let the service figure that part out for me. Instead I only pass in the URL, Title and FolderId. If you have a PostId, you should pass that as well to make the work on the backend less intensive.
The service return signiture looks like this:
HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
<soap12:Body>
<ClipItemsResponse xmlns="http://services.newsgator.com/ngws/svc/PostItem.asmx">
<ClipItemsResult>
<ClippedItem>
<PostId>string</PostId>
<Url>string</Url>
<Title>string</Title>
<FolderId>int</FolderId>
</ClippedItem>
<ClippedItem>
<PostId>string</PostId>
<Url>string</Url>
<Title>string</Title>
<FolderId>int</FolderId>
</ClippedItem>
</ClipItemsResult>
</ClipItemsResponse>
</soap12:Body>
</soap12:Envelope>
You basically get the exact same structure back, but with all the values filled in.
So let's look at a C# example of how to clip the NewsGator homepage to your "My Clippings" folder. You'll need the URL (http://www.newsgator.com), the Title (NewsGator - The RSS Company) and the FolderId (your "My Clippings" folder is always FolderId 0). Lets also assume that you've already added a Web Reference to PostItem.asmx and called it PostService.
public void ClipNewsGatorHomepage()
{
// first, let's setup some variables
string url = "http://www.newsgator.com";
string title = "NewsGator - The RSS Company";
int folderId = 0; // now lets create the PostItem proxy object
PostService.PostItem postWebService = new PostService.PostItem(); // next, create a new ClippedItem object and set it's properties
PostService.ClippedItem clipItem = new PostService.ClippedItem();
clipItem.FolderId = folderId;
clipItem.Title = title;
clipItem.Url = url; // finally, make the call and get the results
PostService.ClippedItem[] clipItemResults =
postWebService.ClipItems(new PostService.ClippedItem[] { clipItem }); // do whatever with the results
}That's it! Now you've clipped the NewsGator Homepage to your "My Clippings" folder!
WS-Education
Posted by gordonw on October 25, 2006
Permalink
| Comments (0)
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
Posted by gordonw on October 17, 2006
Permalink
| Comments (0)
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:
- 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.
- 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.
- 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.
- 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:
- 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.
- 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
Posted by gordonw on October 12, 2006
Permalink
| Comments (0)
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.
Testing Conformance
Posted by gordonw on May 30, 2006
Permalink
| Comments (0)
| TrackBack (0)
While parsing syndicated feeds isn't explicitly a function of the NewsGator API, it is a concern of client applications. If you're getting news through NewsGator (which is the only reliable way to do sync with NewsGator at this point), you get NewsGator's version of the feed, after it's possibly been though some fixup - since NewsGator does liberal parsing, we'll attempt to clean up invalid XML. You also get our understanding of the content, so if we have bugs in conformance, API clients will inherit these issues. First of all, any issues with conformance should be directed to support@newsgator.com, and we will make every effort to fix them. Secondly, as we find example feeds that either represent conformance tests, or have caused problems for NewsGator's parser in the past, we add them to a NewsGator account specifically intended for conformance tests. You can get an OPML version of the subscription list, which is useful for your own testing, or for loading into your NewsGator account for your own conformance testing.
Give it a REST
Posted by gordonw on April 5, 2006
Permalink
| Comments (0)
news
We quietly released a REST version of the NewsGator API yesterday, but Kevin Burton noticed, and so did Brian Dennis. This API should be considered Beta at this point, mainly because we haven't written a real production application against the API. Also there's a some functionality missing from the REST API, most notably, there's very limited support for operations on folders.
In fact, there's been a REST version of the API since the beginning, and all three of our client side products (NG Mail, FeedDemon, and NetNewsWire) use the Feed.aspx endpoint to retrieve news. So even though Kevin said the API was formerly SOAP, the plan is to maintain the REST and SOAP APIs in parallel.
NewsGator API Best Practices
Posted by gordonw on February 3, 2006
Permalink
| Comments (2)
| TrackBack (0)
Nick Bradbury posted on Coming soon: super-fast synching in FeedDemon. It's true, Nick Bradbury, Nick Harris (the dev for NewsGator Outlook, AKA the "less famous Nick"), Brent Simmons, and I all spent an hour talking about how to use the API. Nick and Brent had missed some details on how to use the API. One of the big points developers seem to miss is the whole point of the sync token; devs seem to have a hard time with this concept, so they ignore it.
The sync token was introduced into the API because we had concerns about bandwidth usage, and because SOAP doesn't have anything like Conditional GET, the sync token was the answer for the SOAP interface. With the sync token, as Nick noted, NewsGator Online will tell you what feeds have content that you haven't seen before, based on your sync token. Maybe an example would help. Assuming you made a call to Subscription.asmx/GetSubscriptionList, and this <outline> was in the result set:
<outline title="ranchero.com"
text="ranchero.com" ng:id="43"
xmlUrl="http://ranchero.com/xml/rss.xml"
htmlUrl="http://ranchero.com/" description="News and software for smart people. Mostly Mac." ng:syncXmlUrl="http://services.newsgator.com/ngws/svc/Feed.aspx/43"
ng:folderId="0"
ng:unseen="True"
ng:unread="True"
ng:private="False"
xmlns:ng="http://newsgator.com/schema/opml" />
The important things here are the ng:unseen and ng:unread attributes. ng:unseen="True" tells you that based on the Sync token you sent, this feed has news that you haven't seen from this location. ng:unread="True" tells you that there's at least one unread post in the feed - read states are the same across all locations. So if you had a location that wanted to see only unread posts, you'd use ng:unread to tell you that you needed to get news. If you want to get content, regardless of read state, unseen is the deciding factor in whether you need to retrieve a feed. Unseen and unread are the 2 points you need to make a decision on. If you have a lightweight client that just wants to look at unread posts, then you use ng:unread. FeedDemon and products like it use ng:unseen to determine whether to retrieve the feed. The big win in both these situations is that you don't have to retrieve every feed in your subscription list. With the normal situation, you have to at least poll the feed; even though a 304 is a lightweight operation on the network, there's still network delays in connection establishment. So this is where the download savings Nick's talking about come from.
One last word on locations: locations are intended to line up 1:1 with the user application / machine tuple. In fact, one good method for creating a location is to combine the application name and machine name, for instance NetNewsWire_Gordonslaptop. The normal situation is that a user uses one aggregator per machine they own, but if there's a chance the user will switch aggregators, having a unique name will keep each instance from stepping on other instances.
More on PHP
Posted by gordonw on December 8, 2005
Permalink
| Comments (2)
| TrackBack (0)
