Coder Social home page Coder Social logo

thumbtack's Introduction

Thumbtack - The best Pinboard API client for Ruby

GitHub Actions badge Codecov Inline Docs

Description

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.
  • Ruby-isms
    Use regular Ruby types and let Thumbtack convert it to parameters acceptable to Pinboard (i.e. use true/false instead of 'yes'/'no').
  • Documentation
    Thorough documentation of the usage and API is a top priority for Thumbtack. No question should be unanswered.

Usage

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

Add bookmarks

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

client.posts.delete('http://theinternate.com')

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

Remove tags

client.tags.delete('api')

Rename them

client.tags.rename('delicious', 'pinboard')

Get your secret RSS key

client.user.secret

Retrieve your API key

client.user.api_token

Fetch summaries of all notes (no text)

client.notes.list

Then fetch the full note

client.notes('8e5d6964bb810e0050b0')

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 Note and NoteSummary objects returned from Notes#list and Notes#get.

Requirements

  • Ruby 2.3.6+, but you're already on 2.5+, right?
  • Nothing else. No gem dependencies, nothing.

Installation

The best way to install Thumbtack is with RubyGems:

$ [sudo] gem install thumbtack

API Documentation

http://theinternate.com/thumbtack

Contribute

If you'd like to make some changes to Thumbtack, start by forking the repo on GitHub:

http://github.com/nwjsmith/thumbtack

The best way to get contributions merged into Thumbtack:

  1. Clone down your fork.
  2. Create a well-named topic branch for your change
  3. Make your change.
  4. Add tests and make sure everything passes (see the section on running the tests below).
  5. If you are adding new functionality, document it in the README.
  6. Do not change the version number.
  7. If necessary, rebase your commits into logical chunks, with no failing commits.
  8. Push the branch to GitHub.
  9. 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:

maciej:C9044F4047891CEA74FE

License

Thumbtack is released under the MIT License.

thumbtack's People

Contributors

nwjsmith avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

Forkers

just3ws

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.