API Specification

This document attempts to describe the goread API. It is designed for mobile and other apps for use beyond the web client.

Authorization

Goread runs on App Engine and uses Google's authentication. Refer to this article for some accurate but old information about how to authorize. Also see the goread android client's authorization implementation.

API calls

There are three main API calls used:

1. Fetch unread items and feed data
2. Fetch item contents
3. Mark items read

Fetch unread items and feed data

Takes no arguments.

url: /user/list-feeds

Returns object with the following keys (keys not listed here are used by the web client and can be ignored):

• Opml: an array of Outline objects. These objects are either a feed or another Outline with a list of feeds. If it is a feed, the Outline property will be populated with an array of Outlines and the Title property will be set to the folder name. If it is a feed, the XmlUrl and HtmlUrl properties will be set. XmlUrl is the feed URL, HtmlUrl is the feed's homepage URL.
• Stories: an object of with keys as feed XmlUrls and values as arrays of Story objects, which are the unread feed items. A Story contains an Id, Title, Link, Created date, and content Summary. Feeds with no unread items are still in this array, but have an empty array as their value.
• Feeds: an array of Feed objects. A Feed object has a Url, Title, Checked date, NextUpdate date, Errors count (> 0 if this feed is currently experiencing update errors), and a 16x16 Image icon URL.