Thumbtack - The best Pinboard API client for Ruby
Thumbtack is a simple Ruby client for the Pinboard API.
There are other Pinboard API clients for Ruby, but there are a few things that set Thumbtack apart:
- Zero dependencies
Thumbtack requires only a few things from Ruby's standard library.
- Clean and consistent API
Required arguments in Pinboard's API are required arguments in Thumbtack's method calls. With only one exception, Thumbtack's API mirrors Pinboard's 1-to-1.
- Client-side validation
Pinboard has clearly defined rules about data types and Thumbtack enforces them.
Use regular Ruby types and let Thumbtack convert it to parameters acceptable to Pinboard (i.e. use
Thorough documentation of the usage and API is a top priority for Thumbtack. No question should be unanswered.
Initialize a client with your Pinboard username and API token
client = Thumbtack::Client.new(username, token)
Fetch the most recent time a bookmark was added, updated, or deleted
update_time = client.posts.update
client.posts.add('http://theinternate.com', 'The Internate') client.posts.add('http://theinternate.com', 'The Internate', extended: 'The personal website of Nate Smith', tags: ['awesome', 'essential'])
Delete them too
Retrieve bookmarks by tag or other filters
tagged_webdev = client.posts.get(tag: 'webdev') tagged_webdev_and_ruby = client.posts.get(tag: ['webdev', 'ruby']) pinboard_bookmark = client.posts.get(url: 'http://www.pinboard.in')
Fetch recently added bookmarks
recent_bookmarks = client.posts.recent
Get bookmark creation dates with a count of bookmarks created
dates_with_counts = client.posts.dates(tag: 'argentina')
Get every bookmark from the account
all_bookmarks = client.posts.all
Fetch popular and recommended tags for a URL
tag_suggestions = client.posts.suggest('http://blog.com/')
Find every tag with their usage count
tags_with_counts = client.tags.get
Get your secret RSS key
Retrieve your API key
Fetch summaries of all notes (no text)
Then fetch the full note
The one inconsistency between Thumbtack and Pinboard
Thumbtack tries hard to mimic the Pinboard API, BUT: Pinboard's notes have an attribute named
hash. Unfortunately, this collides with a special method in Ruby. To work around this, Thumbtack renames the
hash attribute to
digest in the
NoteSummary objects returned from
- Ruby 2.3.6+, but you're already on 2.5+, right?
- Nothing else. No gem dependencies, nothing.
The best way to install Thumbtack is with RubyGems:
$ [sudo] gem install thumbtack
If you'd like to make some changes to Thumbtack, start by forking the repo on GitHub:
The best way to get contributions merged into Thumbtack:
- Clone down your fork.
- Create a well-named topic branch for your change
- Make your change.
- Add tests and make sure everything passes (see the section on running the tests below).
- If you are adding new functionality, document it in the README.
- Do not change the version number.
- If necessary, rebase your commits into logical chunks, with no failing commits.
- Push the branch to GitHub.
- Send a pull request to the nwjsmith/thumbtack project.
Run the tests
$ bundle install # Run only the unit tests (no communication/authentication with Pinboard) $ bundle exec rake test:unit # Run the full test suite (will communicate with Pinboard) $ bundle exec rake test
Note to run the full test suite, copy and paste your API Token into the
test/auth_token.txt file. It should look something like this:
Thumbtack is released under the MIT License.