Skip to content
This repository has been archived by the owner on Mar 16, 2020. It is now read-only.

API Specification

Jump to bottom
Matt Jibson edited this page Jan 28, 2014 · 2 revisions

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

All exchange done as JSON.

Fetch unread items and feed data

Used to fetch the user's OPML (feed and folder layout), unread items, and feed information (like icon URLs).

url: /user/list-feeds

Takes no arguments. 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.

Fetch item contents

url: /user/get-contents

Takes a request payload as a list of objects. The objects have a Feed property as the XmlUrl of the feed, and a Story property as the Id of the story item. For example:

[{"Feed":"http://feeds.arstechnica.com/arstechnica/everything","Story":"http://arstechnica.com/?p=400263"},
{"Feed":"http://feeds.arstechnica.com/arstechnica/everything","Story":"http://arstechnica.com/?p=402993"}]

It returns an array of strings which are the story item contents in the same order as the request.

Mark items read

Used to mark unread items as read. There is no API call to mark all read.

url: /user/mark-read

Takes the same parameters as /user/get-contents, but returns nothing.

Clone this wiki locally