Saying stuff about stuff.

Ruby Medium API Client

Medium have a few official API clients (Go / Node / Python) but there isn’t one for Ruby and although there already appear to be (at least) a couple of “unofficial” Ruby Medium API clients I wasn’t entirely convinced by them (lack of tests / lack of source code).

After looking over Medium’s API docs and their existing clients — each of which is barely more than a single file — I decided to write my own Ruby Medium API client. It does little more than communicate with the correct endpoints and convert to and from JSON; I’d even argue that it’s thinner than the official clients as, for example, it doesn’t attempt to know the list of valid publishing licences or statuses or the valid attributes for a post — which seems like a losing game at the best of times but particularly for an “unofficial” client.

Medium’s API docs are particularly useful as they provide example HTTP responses for each endpoint making it easy to test by mocking responses with Webmock — in fact my first work on the library was test-first on a train with no internet*. I’ve been using it for a while as I now cross-post on Medium, it’s working well and helping to smooth my publishing flow (as opposed to doing it manually which is time-consuming and error-prone).

Here’s how to use it to create a post that points back to a canonical URL (an access token is required):

client =
  canonicalUrl: '',
  content: '<p>Some interesting words.</p>',
  contentFormat: 'html',
  publishStatus: 'draft',
  title: 'Hello World',

* Pro-tip: prepare for an internet-less train journey by queueing up docs that might be required. Also, always use the most excellent DevDocs which feels like a web app from the future.