PinboardApi

Description

A Ruby API client for Pinboard.in, the bookmarking website for introverted people in a hurry.

This client aims to cover all of the Pinboard API v1.

Requirements

You must have a paid Pinboard account to use the API. It is a great service and you can signup here if you don't already have an account.
Currently tested on the following Ruby versions:
- 1.9.2
- 1.9.3
- JRuby (1.9 mode)

Note: Specs are currently passing on Rubinius with RBXOPT=-X19 on my local machine but there is a failing spec on Travis CI. I will update the README with official support for Rubinus once everything runs smoothly on Travis.

Installation

Add this line to your application's Gemfile:

gem "pinboard_api"

And then execute:

$ bundle

Or install it yourself as:

$ gem install pinboard_api

Getting Started

You will need to set your username and password for the Pinboard service:

PinboardApi.username = "phlipper"
PinboardApi.password = "[REDACTED]"

Alternately, you may use the new auth_token method:

PinboardApi.auth_token = "[REDACTED]"

You may also set the SSL options which will be passed through to Faraday:

PinboardApi.ssl_options = { ca_file: "/opt/local/share/curl/curl-ca-bundle.crt" }

Usage

The PinboardApi namespace implements the 3 primary object types: Post, Tag, and User.

Post

posts/update - Check to see when a user last posted an item.

PinboardApi::Post.last_update
# => 2012-07-07 04:18:28 UTC

posts/add - add a new bookmark

attributes = { url: "http://phlippers.net/pinboard_api", description: "A Ruby client for the Pinboard.in API", tags: %[ruby awesomesauce] }

post = PinboardApi::Post.new(attributes)
post.save
# => #<PinboardApi::Post:0x007fb42d905a68 @description="A Ruby client for the Pinboard.in API", @extended=nil, @hash=nil, @meta=nil, @url="http://phlippers.net/pinboard_api", @tags="ruby awesomesauce", @time=2012-07-13 23:03:34 -0700>

post = PinboardApi::Post.new
post.url = attributes[:url]
post.description = attributes[:description]
post.save

PinboardApi::Post.create(attributes)

posts/delete - delete an existing bookmark

post = PinboardApi::Post.find(url: "https://pinboard.in/u:phlipper").first
post.destroy
# => #<PinboardApi::Post:0x007ffcb5166cf0 @description="Pinboard - antisocial bookmarking", @extended="", @hash="bc857ba651d134be0c9a5267e943c3ce", @url="https://pinboard.in/u:phlipper", @meta=nil, @tags="test", @time="2012-07-11T09:16:14Z">

PinboardApi::Post.destroy("https://pinboard.in/u:phlipper")
# => #<PinboardApi::Post:0x007f98d6946d78 @description="Pinboard - antisocial bookmarking", @extended="", @hash="bc857ba651d134be0c9a5267e943c3ce", @url="https://pinboard.in/u:phlipper", @meta=nil, @tags="test", @time="2012-07-11T09:17:36Z">

posts/get - get bookmark for a single date, or fetch specific items by URL

PinboardApi::Post.find(tag: "test")
# => [#<PinboardApi::Post:0x007fdce4547388 @description="Test.com – Certification Program Management – Create Online Tests with This Authoring, Management, Training and E-Learning Software", @extended="", @hash="dbb720d788ffaeb0afb7572104072f4a", @url="http://test.com/", @tags="test junk", @time="2012-07-07T04:18:28Z">, ...]

PinboardApi::Post.find(hash: "dbb720d788ffaeb0afb7572104072f4a", meta: "yes")
PinboardApi::Post.find(dt: Date.parse("2012-07-07"))

posts/dates - list dates on which bookmarks were posted

PinboardApi::Post.dates
# => [{"count"=>1, "date"=>#<Date: 2012-07-10 ((2456119j,0s,0n),+0s,2299161j)>}, {"count"=>3, "date"=>#<Date: 2012-07-08 ((2456117j,0s,0n),+0s,2299161j)>}, ...]

PinboardApi::Post.dates(tag: "ruby")

posts/recent - fetch recent bookmarks

PinboardApi::Post.recent
# => [#<PinboardApi::Post:0x007ffe150e1fd0 @description="Techniques to Secure Your Website with Ruby on Rails..."> ...]

PinboardApi::Post.recent(count: 3)
PinboardApi::Post.recent(tag: "ruby")
PinboardApi::Post.recent(count: 25, tag: ["ruby", "programming"])

posts/all - fetch all bookmarks by date, tag, or range

PinboardApi::Post.all
# => [#<PinboardApi::Post:0x007ffe150e1fd0 @description="Techniques to Secure Your Website with Ruby on Rails..."> ...]

PinboardApi::Post.all(tag: %w[ruby programming], meta: true, results: 30)
PinboardApi::Post.all(start: 50, fromdt: 2.weeks.ago, todt: 1.week.ago)

posts/suggest - fetch popular and recommended tags for a url

PinboardApi::Post.suggest("http://blog.com")
# => {"popular"=>["hosting", "blogs", "blog", "free"], "recommended"=>["blog", "blogging", "blogs", "free"]}

Tag

tags/get - fetch all tags

PinboardApi::Tag.all
# => [#<PinboardApi::Tag:0x007fdce41f4f00 @name="leadership", @count=1>, #<PinboardApi::Tag:0x007fdce41f4e10 @name="date", @count=1>, ... ]

PinboardApi::Tag.find("leadership")
# => #<PinboardApi::Tag:0x007fdce4827eb8 @name="leadership", @count=1>

tags/delete - delete a tag from all bookmarks

tag = PinboardApi::Tag.find("foo")
tag.destroy
# => #<PinboardApi::Tag:0x007fdce45f56e0 @name="foo", @count=1>

PinboardApi::Tag.destroy("foo")
# => #<PinboardApi::Tag:0x007fdce45f20f8 @name="foo", @count=1>

tags/rename - rename a tag

tag = PinboardApi::Tag.find("foo")
# => #<PinboardApi::Tag:0x007fdce461bcc8 @name="foo", @count=1>

tag.rename("foo2")
# => #<PinboardApi::Tag:0x007fdce4c4bb48 @name="foo2", @count=1>

User

user/secret - get the secret RSS token (allows viewing user's private RSS feeds)

PinboardApi::User.secret
# => "c3b0f4073ea37c4b1df5"

TODO

Implement support for rate limiting

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Added some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

License

pinboard_api

Freely distributable and licensed under the MIT license.
http://phlippers.net/