Api Documentation

Authenification

Follow the few easy steps below to make your first Reader.is API call using OAuth 2.0.

Overview of the OAuth 2.0 Authentification Flow

     +----------+          Client Identifier      +---------------+
     |         -+----(A)-- & Redirection URI ---->|               |
     |  User-   |                                 | Authorization |
     |  Agent  -+----(B)-- User authenticates --->|     Server    |
     |          |                                 |               |
     |         -+----(C)-- Authorization Code ---<|               |
     +-|----|---+                                 +---------------+
       |    |                                         ^      v
      (A)  (C)                                        |      |
       |    |                                         |      |
       ^    v                                         |      |
     +---------+                                      |      |
     |         |>---(D)-- Authorization Code ---------'      |
     |  Client |           & Client Secret                   |
     |         |                                             |
     |         |<---(E)----- Access Token -------------------'
     +---------+         & Push Token & User Id
	 

Step 1. Register your application

Register here your application with Reader.is to receive an API key. This unique key helps us identify your application and lets you make API calls. Once you've registered your Reader.is app, you will be provided with an API Secret Key and your App Id. For the safety of your application please do not share your Secret Key.



Step 2. Get an access token

Access token are unique to a user and an app. You need access tokens in order to make API calls to Reader.is on behalf of the user who authorized your application. Follow the two steps below to get one:

a. Generate Authorization Code by redirecting user to Reader.is's authorization dialog

(A)

Redirect

http://reader.is/oauth/?client_id={Your App Id}
                                      &redirect_uri={Your Redirect Uri}
Parameter Description Possible Errors
client_id Required. Value of your App ID given when you registered your application with Reader.is. Invalid client id; Passed multiple client ids; Passed an empty value; Missing the parameter
redirect_uri Optional. Encoded URI in your app where users will be sent after authorization. URI can use http or https. If not set the default redirect_uri specified when registering the app will be used. Example: http://www.reader.is


(C)
If the user authorizes your application they will be redirected to the redirect_uri that you specified in your request above along with a temporary authorization_code.

Upon successful authorization, the redirected URL should look like:
{Your Redirect Uri}/?code={Authorization Code}

b. Request Access Token by exchanging the authorization_code for it

(D)

POST

http://api.reader.is/access_token?client_id={Your App Id}
                                                           &client_secret={Your Secret Key}
                                                           &code={Authorization Code}
Parameter Description Possible Errors
client_id Required. Value of your App ID given when you registered your application with Reader.is. Different client-id than used during authorization code generation; Invalid client id; Passed multiple client ids; Passed an empty value; Missing the parameter
client_secret Required. Value of your secret key given when you registered your application with Reader.is. Passed invalid value; Passed multiple values; Passed an empty value; Missing the parameter
code Required. Value of authorization_code that you got in the previous step. Passed invalid value; Authorization code expired; Passed an empty value; Missing the parameter


(E)
The response will be a JSON object:
{"user_id":"{USER ID}","token":"{ACCESS TOKEN}","push_token":"{PUSH TOKEN}"}
Parameter Type Description
token STRING Access token that the app will need to make API calls on behalf of the user.
user_id push_token If you activated the push API, the push toke will be sent to your push url, as GET parameter 'push_token', when a user performs an action that is tracked by your application.

Step 3. Make the API calls

You can now have the toke that you can use to make API calls on behalf of this user.

API Calls

Stream Api

Get Home stream If no additional parameter is sent a timeordered list of articles from feeds the user follows is returned.

GET

http://api.reader.is/ {user_id} /?client_id={Your App Id}
                                                           &token={User Token}
                                                           & {Additional parameters}
Additional parameters
Parameter Description
GET unr=1 Get only not read articles
GET unr=1Get only not read articles
GET unr=1 Get only not read articles
GET unr=2 Get only not read articles orderd by oldes first
GET t=1 Get best articles from last 24 hours
GET t=7 Get best articles from last 7 days
GET s={source_id} Get articles only from that source
GET list={list_id} Get articles only from that list
GET starred=1 Get starred articles
GET read=1 Get read articles
GET from= {starting article} default 0
GET items= {number of items to return} default 30, maximal 60

User Profile Data Api

Get sources a user follows

GET

http://api.reader.is/ {user_id} /sources/?client_id={Your App Id}
                                                           &token={User Token}


Successful response body:

[
	{
		"id":"{source id}",
		"name":"{source name}",
		"sub_name":"{source/feed dettailed name}",
		"feed_url":"{feed url}",
		"icon":"rd_5907_66.png", //source icon avaiable at  http://reader.is/imgs/...
		"rating":5 //user rating
	},
	..
]


Get lists a user follows

GET

http://api.reader.is/ {user_id} /lists/?client_id={Your App Id}
                                                           &token={User Token}


Successful response body:

[
	{
		"id":"{source id}",
		"name":"{source name}",
		"url":"{list url}"
	},
	..
]


Perform Actions on Reader.is API

Read an article

POST

http://api.reader.is/ {user_id} /read/
Post Input Fields //as json or as post fields

 {
	"token" : "{user_token}",
	"client_id" : "{client_id}",
	"article_id" : "{article_id}"
}


Successful response body:

{"success":"1"}


Star an article

POST

http://api.reader.is/ {user_id} /star/
Post Input Fields //as json or as post fields

 {
	"token" : "{user_token}",
	"client_id" : "{client_id}",
	"article_id" : "{article_id}"
}


Successful response body:

{"success":"1"}


Add a Feed

POST

http://api.reader.is/ {user_id} /addfeed/
Post Input Fields //as json or as post fields

 {
	"token" : "{user_token}",
	"client_id" : "{client_id}",
	"feed" : "{feed url}",
	"updatetime" : "{time every x hours the feed should be crawled}", //optional
	"category" : "{category id of the feed}", //optional
	"rating" : "{rating of the feed}", //optional 1-5
	"list" : "{id of the list the feed should be added or 'new' if a new list should be created}", //optional
	"new_list" : "{name of a new list the feed should be added}" //optional, to use when list=new
}


ParameterData typeRequired Description Possible Errors
tokenString Required. The access token you got when the user authorized the app. Invalid token; token does not match user id; passed multiple tokens; passed an empty value; missing the parameter
client_idINT Required. Value of your App ID given when you registered your application with Reader.is. Invalid client id; Passed multiple client ids; Passed an empty value; Missing the parameter
feedString Required. URL of the RSS or Atom feed that should be added. Invalid RSS or Atom Feed; Passed multiple values Passed an empty value; Missing the parameter
updatetimeINT 0-127 Optional. Time every how often (in hours) the feed should be crawled Invalid data type
categoryINT Optional. Category id of the feed Invalid data type; invalid category id
ratingDECIMAL 0-5 Optional. Rating the user assigns to the feed with 5 the highest value. Invalid data type; invalid rating
listINT or String 'new' Optional. Id of the list the feed should be added to or 'new' if a new list should be created. Invalid data type;
new_listINT or String 'new' Optional. Name of a new list the feed should be added. GET list has not value 'new'


Examples

Basic Php

Basic example on how to authorize a user an show him the sources and lists he follows, and his home stream.

<?
$app_id 
"YOUR APP ID HERE";
$app_secret "YOUR APP SECRET HERE";
$my_url "YOUR URL HERE";  

function 
get_remote_file($url1//function to get remote files using curl
{
    
$ch curl_init();
    
    
curl_setopt($chCURLOPT_HEADER0);
    
curl_setopt($chCURLOPT_RETURNTRANSFER1); //Set curl to return the data instead of printing it to the browser.
    
curl_setopt($chCURLOPT_URL$url1);
 
    
$data curl_exec($ch);
    
curl_close($ch);
 
    return 
$data;

}
 
if (isset(
$_REQUEST["code"])) 
{  
    
$code $_REQUEST["code"];  

else 
{    
    
$code "";
    
$dialog_url "http://reader.is/oauth/?client_id="  
        
$app_id "&redirect_uri=" urlencode($my_url);  
    
    echo(
"<script> location.href='" $dialog_url "'</script>");  
    exit;
}  
if(
$code != ""){

$token_url "http://api.reader.is/access_token?client_id="$app_id "&client_secret=".$app_secret "&code=" $code;

$result get_remote_file($token_url);  
$user_data json_decode($resulttrue);  

echo 
"<html><head><style type='text/css' >
.icon {
    margin: 1px;
    vertical-align: middle;
    width: 20px;
}
</style></head><body>"
;
echo
"<h2>User id and access tokens that could be used for later API calls without requiring an additional authentification</h2>";
echo
"<pre>";
print_r($user_data );
echo
"</pre>";

$resultme get_remote_file("http://api.reader.is/".$user_data ['user_id']."/lists/?client_id=".$app_id."&token=" $user_data ['token']); //Get sources the user follows
$data json_decode($resultmetrue);  
echo
"<h2>Lists I follow</h2>";
//echo"<pre>"; //if you want to print the raw response and see all the data you could use
//print_r($data);
//echo"</pre>";
foreach ($data as $value) {
    echo 
"<div><a  href='{$value['url']}'> {$value['name']} </a></div>\n";
}

$resultme get_remote_file("http://api.reader.is/".$user_data ['user_id']."/sources/?client_id=".$app_id."&token=" $user_data ['token']); //Get sources the user follows
$data json_decode($resultmetrue);  
echo
"<h2>Sources I follow</h2>";

//echo"<pre>"; //if you want to print the raw response and see all the data you could use
//print_r($data);
//echo"</pre>";
foreach ($data as $value) {
    echo 
"<div><a  href='{$value['feed_url']}'><img src='http://reader.is/imgs/{$value['icon']}'  class='icon'> {$value['name']} ({$value['sub_name']})</a></div>\n";
}

$resultme get_remote_file("http://api.reader.is/".$user_data ['user_id']."/?client_id=".$app_id."&token=" $user_data ['token']);  //Get the home article stream
$data json_decode($resultmetrue);  
echo
"<h2>The latest articles from my feeds</h2>";
//echo"<pre>"; //if you want to print the raw response and see all the data you could use
//print_r($data);
//echo"</pre>";
foreach ($data['data'] as $value) {
    echo 
"<div><h3><a  href='{$value['link']}'>{$value['title']}</a></h3><img src='http://reader.is/imgs/{$value['s_img']}' class='icon'> {$value['name']} <br><br>{$value['description']}</div>\n";
}

echo 
"</html>";
}
?>

Push API - Webhooks

The push API allows you to be notified whenever a user performs a specific action (for the moment only when he stars an article). When a user performs the specific action we will call the url you specified with the method you specified (POST or GET). When you edit your app you will have a point "Push API" where you can specify the webhook url, the HTTP method, and the data to be sent. In the url and the post body you can specify variables that will be replaced with the actual value for the user or article performing the tracked action. Following variables could be used:
VariableString to use in the URL - Post body Description
User Id%user_id% The Reader.is user id of the user performing the tracked action.
Push Token%push_token% The push token of the user performing the tracked action.
Link%link% The encoded url of the article that the tracked action has been performed to (starred,..).
Article id%article_id% The Reader.is artcle id of the article that the tracked action has been performed to (starred,..).

Comments