0.0
No commit activity in last 3 years
No release in over 3 years
A Ruby client for the Pinboard.in API
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

Runtime

~> 0.8.0
~> 0.5.1
 Project Readme

PinboardApi Build Status Code Climate

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
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)
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")
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)
PinboardApi::Post.suggest("http://blog.com")
# => {"popular"=>["hosting", "blogs", "blog", "free"], "recommended"=>["blog", "blogging", "blogs", "free"]}

Tag

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>
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>
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

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

License

pinboard_api