Skip to content

Latest commit

 

History

History
430 lines (257 loc) · 11 KB

README.md

File metadata and controls

430 lines (257 loc) · 11 KB
Raw

The Old Reader API

TODO

  • Tagging items
  • OAuth

Apps

See complete list of apps and extensions on theoldreader.com.

Libraries

Contributing

You are welcome to improve documentation, please feel free to send us pull requests with your adjustments.

If you find any bugs or feel that something is not working as expected, please create a github issue or contact us at api@theoldreader.com.

Current API

Current API tries to mimic the unofficial Google Reader API.

Please note that even though you can use API both via http and https, we highly encourage you to use https for security reasons.

Differences

  • Currently only json format is supported
  • We use BSON ObjectId for user, item, subscription identifiers (example: 00157a17b192950b65be3791)
  • We also use ObjectId in Stream Ids instead of URL (example: feed/00157a17b192950b65be3791)
  • Current user id is replaced with - in state/label strings (examples: user/-/state/com.google/reading-list, user/-/label/Folder)

Authentication

All requests you will be sending to the API should be authenticated by a token.

Please note that The Old Reader allows users to sign in via OAuth (Google or Facebook), but the only way to get an API token for a now is to set password in settings and use it for authentication.

Getting a token

Sample request:

curl -d "client=YourAppName&accountType=HOSTED_OR_GOOGLE&service=reader&Email=test@krasnoukhov.com&Passwd=..." https://theoldreader.com/accounts/ClientLogin

Sample response:

SID=none
LSID=none
Auth=LyTEJPvTJiSPrCxLu46d

Please note that you can also get a token by requesting following url: /reader/api/0/accounts/ClientLogin

Also you might want to add output=json to POST parameters for corresponding result.

Using a token

Include Authorization: GoogleLogin auth=TOKEN HTTP header in all your requests. For example:

Authorization: GoogleLogin auth=LyTEJPvTJiSPrCxLu46d

Errors

All errors except Adding subscription have following format:

XML:

<?xml version="1.0" encoding="UTF-8"?>
<errors type="array">
  <error>XML output currently is not supported</error>
</errors>

JSON:

{
	errors: [
		"Temporary unavailable, please try later"
	]
}

Status

After a couple unsuccessful requests you might try to obtain current The Old Reader status:

GET https://theoldreader.com/reader/api/0/status?output=json

Everything is fine:

> curl https://theoldreader.com/reader/api/0/status?output=json
{"status":"up"}

Something is wrong:

> curl https://theoldreader.com/reader/api/0/status?output=json
{"status":"down","description":"Database issues","redirect":"http://status.theoldreader.com"}

Generic methods

Token

GET https://theoldreader.com/reader/api/0/token

> curl https://theoldreader.com/reader/api/0/token -H "Authorization: GoogleLogin auth=LyTEJPvTJiSPrCxLu46d"
LyTEJPvTJiSPrCxLu46d

Added for compatibility.

User info

GET https://theoldreader.com/reader/api/0/user-info?output=json

> curl https://theoldreader.com/reader/api/0/user-info?output=json -H "Authorization: GoogleLogin auth=LyTEJPvTJiSPrCxLu46d"
{"userId":"00157a17b192950b65be3791","userName":"Test","userProfileId":"00157a17b192950b65be3791","userEmail":"test@krasnoukhov.com","isBloggerUser":false,"signupTimeSec":1370709105,"isMultiLoginEnabled":false,"isPremium":true}

Preferences list

GET https://theoldreader.com/reader/api/0/preference/list?output=json

Added for compatibility.

Friends

Friend list

GET https://theoldreader.com/reader/api/0/friend/list?output=json

Contains friends list.

Following/unfollowing a friend

POST https://theoldreader.com/reader/api/0/friend/edit

Parameters:

# Follow
action=addfollowing

# Or unfollow
action=removefollowing

# By id
u=00157a17b192950b65be3791

# Or by stream id
u=user/00157a17b192950b65be3791/state/com.google/broadcast

Comments

Adding a comment

POST https://theoldreader.com/reader/api/0/comment/edit

Parameters:

action=addcomment
i=tag:google.com,2005:reader/item/00157a17b192950b65be3791
comment=Hello

Folders

Tag list

GET https://theoldreader.com/reader/api/0/tag/list?output=json

Contains folder list.

Stream preferences list

GET https://theoldreader.com/reader/api/0/preference/stream/list?output=json

Contains information about subscriptions ordering for root (folders and subscriptions ordering) and user folders (subscriptions ordering).

Update stream preferences

POST https://theoldreader.com/reader/api/0/preference/stream/set

Added for compatibility.

Renaming folder

POST https://theoldreader.com/reader/api/0/rename-tag

Parameters:

s=user/-/label/Folder
dest=user/-/label/NewFolder

Removing folder

POST https://theoldreader.com/reader/api/0/disable-tag

Removes folder and moves subscriptions to default folder.

Parameters:

s=user/-/label/Folder

Subscriptions

Unread count

GET https://theoldreader.com/reader/api/0/unread-count?output=json

Contains unread counts for all items (reading list), each folder, subscription and friend.

Subscriptions list

GET https://theoldreader.com/reader/api/0/subscription/list?output=json

Each subscription contains url, htmlUrl and iconUrl.

Subscriptions OPML

GET https://theoldreader.com/reader/subscriptions/export

Adding subscription

POST https://theoldreader.com/reader/api/0/subscription/quickadd?quickadd=blog.theoldreader.com

Successful response:

{"query":"blog.theoldreader.com","numResults":1,"streamId":"feed/00157a17b192950b65be3791"}

Failed response:

{"query":"blog.theoldreader.com","numResults":0,"error":"Feed was not added. You already have 129 subscriptions, your limit is 100. You should upgrade to premium."}

Updating subscription

POST https://theoldreader.com/reader/api/0/subscription/edit

Parameters:

ac=edit

# Stream Id
s=feed/00157a17b192950b65be3791

# Change subscription title
t=Title

# Move subscription to folder with a given title
a=user/-/label/Folder

# Move subscription to default folder (no difference what r is)
r=user/-/label/Folder

Removing subscription

POST https://theoldreader.com/reader/api/0/subscription/edit

Parameters:

ac=unsubscribe
s=feed/00157a17b192950b65be3791 # Stream Id

Items

Item ids

GET https://theoldreader.com/reader/api/0/stream/items/ids?output=json

Parameters:

Filter by stream:

# All items
s=user/-/state/com.google/reading-list

# Read items
s=user/-/state/com.google/read

# Starred items
s=user/-/state/com.google/starred

# Liked items
s=user/-/state/com.google/like

# Shared items
s=user/-/state/com.google/broadcast

# Commented items
s=user/-/state/com.google/broadcast-friends-comments

# Shared by friends
s=user/-/state/com.google/broadcast-friends

# Folder
s=user/-/label/...

# Subscription
s=feed/00157a17b192950b65be3791

# Friend
s=user/00157a17b192950b65be3791/state/com.google/broadcast

Exclude items (please note that this does not work for starred/liked/shared/commented items):

# Only unread
xt=user/-/state/com.google/read

Other parameters:

n=1000 # Limit items
r=o # Reverse sorting
c=… # Continuation
nt=1371645508 # Older than
ot=1371645508 # Newer than

Please note that maximum limit is: 10000 for item ids, 1000 for item contents.

Item contents

POST https://theoldreader.com/reader/api/0/stream/items/contents?output=json

Parameters:

# Item ids
i=tag:google.com,2005:reader/item/00157a17b192950b65be3791&i=…&i=…

# Atom output
output=atom

Stream contents

GET https://theoldreader.com/reader/api/0/stream/contents?output=json

Parameters:

# Same as for ids

# Atom output
output=atom

Also there is an atom feed for specific Stream Id:

GET https://theoldreader.com/reader/atom/feed/00157a17b192950b65be3791

And state:

GET https://theoldreader.com/reader/atom/user/-/state/com.google/read

And folder:

GET https://theoldreader.com/reader/atom/user/-/label/Folder

Marking all as read

POST https://theoldreader.com/reader/api/0/mark-all-as-read

Please note that this does not work for starred/liked/shared/commented items.

Parameters:

# All items
s=user/-/state/com.google/reading-list

# Shared by friends
s=user/-/state/com.google/broadcast-friends

# Folder
s=user/-/label/...

# Subscription
s=feed/00157a17b192950b65be3791

# Friend
s=user/00157a17b192950b65be3791/state/com.google/broadcast

# Older than timestamp in nanoseconds
ts=1371645508000000

Updating items

POST https://theoldreader.com/reader/api/0/edit-tag

Parameters:

# Item ids
i=tag:google.com,2005:reader/item/00157a17b192950b65be3791&i=…&i=…

# Mark as read
a=user/-/state/com.google/read

# Mark as starred
a=user/-/state/com.google/starred

# Mark as liked
a=user/-/state/com.google/like

# Mark as shared
a=user/-/state/com.google/broadcast

# Mark as shared (with note)
a=user/-/state/com.google/broadcast&annotation=Hello

# Mark as unread
r=user/-/state/com.google/read

# Remove starred mark
r=user/-/state/com.google/starred

# Remove liked mark
r=user/-/state/com.google/like

# Remove shared mark
r=user/-/state/com.google/broadcast