README.md

node-readability-api

This is a Node client for the Readability API. It supports the Reader API, Parser API and Shortener API.

Installation

npm install --save readability-api

Usage

Initialize the client

var readability = require('readability-api');

readability.configure({
    consumer_key: 'some_consumer_key',
    consumer_secret: 'some_consumer_secret',
    parser_token: 'some_parser_token'
});

Authentication

Retrieve an OAuth access token and access token secret for a user

readability.xauth('some_username', 'some_password', function (err, tokens) {
  // Use tokens.oauth_token and tokens.oauth_token_secret when creating a Reader API client
})

Reader API

To use the Reader API, create a Reader object using an OAuth token and token secret

var reader = new readability.reader({
  access_token: 'some_access_token',
  access_token_secret: 'some_access_token_secret'
});

User information

// Get information about the current user
reader.user(function (err, user) {
  //...
});

Bookmarks

// Get all bookmarks - response contains both metadata (pagination etc.) and an array of bookmarks
reader.bookmarks(options, function (err, bookmarks) {
   //...
});

// Get a bookmark by its id
reader.bookmark('some_bookmark_id', function (err, bookmark) {
   //...
});

// Add a bookmark - returns the created bookmark
reader.addBookmark('http://some.bookmark.url.com/article.html', function (err, bookmark) {
   //...
});

// Remove a bookmark - success is a boolean
reader.removeBookmark('some_bookmark_id', function (err, success) {
   //...
});

// Archive a bookmark - returns the archived bookmark
reader.archiveBookmark('some_bookmark_id', function (err, bookmark) {
   //...
});

// Unarchive a bookmark - returns the bookmark
reader.unarchiveBookmark('some_bookmark_id', function (err, bookmark) {
   //...
});

// Favourite a bookmark - returns the favourited bookmark
reader.favouriteBookmark('some_bookmark_id', function (err, bookmark) {
   //...
});

// Unavourite a bookmark - returns the bookmark
reader.unfavouriteBookmark('some_bookmark_id', function (err, bookmark) {
   //...
});

Tags

// Get all of the current user's tags - returns an array of tags
reader.userTags(function (err, tags) {
   //...
});

// Get all of the tags for a bookmark - returns an array of tags
reader.tags('some_bookmark_id', function (err, tags) {
   //...
});

// Add tags to a bookmark - returns an array of tags
reader.addTags('some_bookmark_id', ['tag1', 'tag2', 'tag3'], function (err, bookmark) {
    //...
});

// Remove a tag from a bookmark - returns the bookmark
reader.removeTag('some_bookmark_id', 'some_tag_id', function (err, bookmark) {
   //...
});

Articles

// Get a single article
reader.article('some_article_id', function (err, article) {
   //...
});

Parser API

// Create a parser object
var parser = new readability.parser();

// Parse an article
parser.parse('http://some.bookmark.url.com/article.html', function (err, parsed) {
  //...
});

// Get the Parser confidence level - returns a number between 0 and 1
parser.confidence('http://some.bookmark.url.com/article.html', function (err, confidence) {
  //...
});

Shortener API

// Create a shortener object
var shortener = new readability.shortener()

// Create a short URL - returns the short URL as a string and additional URL data
shortener.shorten('http://www.example.com/article.html', function(err, shortUrl, data) {
  //...
});

// Get information about a short URL
shortener.url('some_url_id', function(err, url) {
  //...
});