This documentation covers the NewsGator SOAP interfaces. Most resources are also exposed as REST style endpoints; refer to the NewsGator REST API Documentation for further details.

The NewsGator Online API is designed around operations on the resources mentioned previously. In general, a resource will have list, create, rename, and delete operations defined. However, not all resources support all these operations and some resources support additional operations.

Certain resources in the API will return a sync token as part of the response to a list operation. If the user agent is storing subscription and feed content locally, it can pass the token returned by the last sync in the current sync and NewsGator will use the token to return only the content that is new or changed since the last sync. The sync token is used by the methods that accept it to identify the data that was returned by the last call to this method; when a sync token is passed to a method, the method will return data indicating what content has changed; for example, on the GetSubscriptions method, the result will indicate which feeds have updated since the last call to GetSubscriptions, and on the GetNews method, the result will contain only items that have been added or modified since the last call. This token is opaque and should not be modified by a client. The sync token is always an optional parameter on operations that accept it.

User Agents will typically follow the outline below when working with NewsGator Online:

1. The user agent does a SetState call to update NewsGator Online with any state changes made since the last sync. The result of this call is a list of state changes since the last time this location reported state. A user agent may call SetState at any point; more frequent updates will reduce the size of the message and reduce the likelihood of the user perceiving.
2. The user agent does a GetSubscriptions call to download the subscription list from NewsGator Online, submitting the sync token obtained from the last GetSubscriptions call to enable NewsGator Online to determine which feeds need to be retrieved.
3. For each subscription marked unseen in the result of the GetSubscriptions call, the User Agent downloads an RSS feed indicated by the syncXmlUrl attribute on the subscription, submitting the token obtained from the last download of that URL.

User Agents can adopt the API at various levels; a user agent can synchronize subscriptions, folder structure, or down to the read / deleted states for individual posts. In a full synchronization scenario, the user agent uses NewsGator Online as the source for syndicated data, as opposed to the URL of the actual RSS feed; this allows NewsGator Online to annotate the feed with data that communicates information about the state of the post. Synchronization can be either automatically scheduled or on demand. In all scenarios, NewsGator Online serves as the central synchronization point and is considered the authority on the state of any synchronized resource. Synchronization is based strictly on a "last one wins"; so state on any resource is based upon the last change made to the resource.

It's important to understand the goal of the NewsGator Online API; a post's state is regarded as synchronizable only as long as it remains in the source feed. Simply comparing unread counts between NewsGator Online and the user agent isn't a sufficient test; the concern is that if a user downloads and reads news in one location, and then goes to another location, the user should see a visual indication that a news item has or has not been read that's accurate. It's not so important that the counts of unread items match between NewsGator Online and the user agent, compared to the fact that if you've explicitly read something in one location, it gets marked read in all the other NewsGator locations you use. 

The NewsGator Online API uses the following data formats, with NewsGator-specific extensions:

• RSS 2.0 specificaton, with NewsGator extensions.
• OPML specification with NewsGator extensions.

The general philosophy behind the use of these specifications is that output from any of the NewsGator services should be usable by another application that also understands the specification in question. We've tried to respect established practice with both of these specifications and add extensions only to express concepts unique to NewsGator.

The NewsGator Online API requires that the caller provide NewsGator Online credentials (free signup) in order to call any methods. NewsGator Online accepts HTTP basic and Digest authentication. We recommend that you use HTTP Digest Authentication, or that you use an SSL connection if you must use HTTP Basic authentication.