Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/stve/instapaper

Ruby Client for Instapaper's Full API
https://github.com/stve/instapaper

instapaper

Last synced: 23 days ago
JSON representation

Ruby Client for Instapaper's Full API

Host: GitHub
URL: https://github.com/stve/instapaper
Owner: stve
License: mit
Created: 2011-11-22T00:23:34.000Z (almost 13 years ago)
Default Branch: main
Last Pushed: 2022-02-21T02:46:31.000Z (over 2 years ago)
Last Synced: 2024-09-19T05:39:03.794Z (about 2 months ago)
Topics: instapaper
Language: Ruby
Homepage:
Size: 148 KB
Stars: 95
Watchers: 4
Forks: 18
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE.md

Awesome Lists containing this project

README

# Instapaper

[![Gem Version](http://img.shields.io/gem/v/instapaper.svg)][gem]
![Tests](https://github.com/stve/instapaper/actions/workflows/ci.yml/badge.svg)

[gem]: https://rubygems.org/gems/instapaper

Instapaper is a ruby wrapper for interacting with [Instapaper's Full API](https://www.instapaper.com/api/full). Note that access to the Full API is restricted to Instapaper subscribers only.

## Installation

gem install instapaper

## Usage

This library offers full support for all methods exposed through Instapaper's Full API. Note that Instapaper's API does not support the request-token/authorize workflow. To obtain an access token, use the `access_token` method.

## Changes in 1.0.0

If you've used earlier versions of this library, a lot has changed in version `1.x`. While not a total rewrite, I've changed a number of things based on my experience writing API libraries:

* swapped out Faraday for http.rb
* responses now return custom classes instead of Hashie::Rash objects
* most API methods are more clear as to their behavior (i.e., `#star_bookmark` instead of just `#star`)
* module-based configuration and invocation has been removed, you'll now need to instantiate an `Instapaper::Client` instead (see usage below)
* Improved error handling
* Updates for version 1.1 of Instapaper's API
* Support for Highlights API

## Configuration

```ruby
client = Instapaper::Client.new do |client|
client.consumer_key = YOUR_CONSUMER_KEY
client.consumer_secret = YOUR_CONSUMER_SECRET
client.oauth_token = YOUR_OAUTH_TOKEN
client.oauth_token_secret = YOUR_OAUTH_TOKEN_SECRET
end
```

## Authentication

To obtain an access token via xAuth:

```ruby
client.access_token(username, password)
```

You can also verify credentials once you have received tokens:

```ruby
client.verify_credentials
```

## Bookmark Operations

Retrieve a list of bookmarks:

```ruby
client.bookmarks
```

Add a new bookmark:

```ruby
bookmark = {
title: 'This is the title',
description: 'This is the description',
}

client.add_bookmark('http://someurl.com', bookmark)
```

Remove a bookmark:

```ruby
client.delete_bookmark(bookmark_id)
```

Update read progress:

```ruby
client.update_read_progress(bookmark_id, 0.5)
```

Star/Un-star a bookmark:

```ruby
client.star_bookmark(bookmark_id)
client.unstar_bookmark(bookmark_id)
```

Archive/Un-archive a bookmark:

```ruby
client.archive_bookmark(bookmark_id)
client.unarchive_bookmark(bookmark_id)
```

Move a bookmark to a folder:

```ruby
client.move_bookmark(bookmark_id, folder_id)
```

Obtain the text of a bookmark:

```ruby
client.get_text(bookmark_id)
```

## Folder Operations

To obtain the list of folders:

```ruby
client.folders
```

You can add by passing a name:

```ruby
client.add_folder('eventmachine')
```

And remove folders by referencing a folder by it's id.

```ruby
client.delete_folder(folder_id)
```

Lastly, the folders can be reordered:

```ruby
client.set_order(['folder_id1:2','folder_id2:1'])
```

## Highlights Operations

Obtain highlights for a bookmark:

```ruby
client.highlights(bookmark_id)
```

Add a highlight for a bookmark:

```ruby
highlight = {
text: 'And so we beat on, boats against the current, borne back ceaselessly into the past.',
position: 20,
}

client.add_highlight(bookmark_id, highlight)
```

Remove a highlight:

```ruby
client.delete_highlight(highlight_id)
```

## Documentation

[http://rdoc.info/gems/instapaper](http://rdoc.info/gems/instapaper)

## Contributing

* Fork the project.
* Make your feature addition or bug fix.
* Add tests for it. This is important so I don't break it in a
future version unintentionally.
* Commit, do not mess with Rakefile, gem version, or history.
(if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
* Send me a pull request. Bonus points for topic branches.