API Design Thoughts

I think there should be an example of each of the methods listed here: https://pinboard.in/api#methods

Implementing an example of each API method will help provide vision for the Client API before moving further.

API Inconsistencies

There are some inconsistencies in the Pinboard API that could be addressed in the Ruby client. It really depends if the library should map 1-1 with the HTTP API or if there should be some "sugar" involved.

Example

From https://pinboard.in/api#methods

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

tags/get - fetch all tags

If mirroring the API I think these examples come to mind:

pinboard = Pinboard.new
pinboard.posts.all # fetch all posts
pinboard.tags.get # fetch all tags

I personally find this inconsistency a little annoying, I prefer these examples:

pinboard.posts.all
pinboard.tags.all

Once you go down this route, I think it is okay to break all of the conventions from the API, given that you provide excellent API documentation.

Chad Fowler blogged on this very subject here: http://chadfowler.com/2007/09/05/writing-apis-to-wrap-apis

Rate Limiting, etc.

I am familiar with the "Hardy Client" implementation inside of the Harvested gem, but I wonder if there is a simpler approach using the session proxy pattern, similar to what is in Sunspot. Rather than session though, I think the object that should be proxied is the "connection". More thoughts are needed here, preferably with some example code.