Category Archives: Software Development

Announcing HalClient (for ruby)

HalClient is yet another ruby client library for HAL based web APIs. The goal is to provide an easy to use set of abstractions on top of HAL without completely hiding the HAL based API underneath. The areas of complication that HalClient seeks to simplify are CURIE links regular vs embedded links templated links working […]

Rails vs Node.js

That title got your attention, didn’t it? While trying to make this decision myself recently I really wished some agile manifesto style value statements existed for these two platforms. Now that I have my first production deploy of a app I’m going give it a stab. The Ruby on Rails community prefers: Speed of […]

Would someone please think of the client developers?!?

It seems that most APIs — particularly internal ones — are not designed for ease of use but rather to be easy to implement. No one would expect a human facing product designed that way to be successful. We should not expect APIs to be any different. Web APIs are products in their own right. […]

Zero dot versions

Dear library developers, please knock that shit off immediately. We all seem to accept the wisdom of semantic versioning these days (thank goodness). Somehow, though, it has not occurred to many library developers that locking the first slot of the version to 0 means you give up all those benefits. Incrementing the first slot is […]


Designing the messages (or representations, i’ll use the terms interchangeably) is the most important part of API design. If you get the messages right everything else will flow naturally from them. Of course, there are trade offs that must be made when designing messages. One of those trade offs is how much data to put […]

What do i want to do when i grow up?

Where are the cool innovations of the next decade happening so i can find a job working on them? I am starting to look for a job and for the first time in many years i am not sure what sort of job i want. I have made a good career being on the bleeding […]

Well that was unexpected

I am no longer with GitHub. Working at GitHub was a pretty amazing experience. I enjoyed every single minute of it except for the last half hour or so. However, impermanence is — so i am back on the market. If you need someone who knows a fair bit about web API design, SOA (of […]

Rails tip #72: hands off other’s private parts

In Ruby on Rails the most common way to pass data from the controller to the views is by allowing views direct access to the controller’s instance variables. Encapsulation is one of the cornerstones of software engineering. Why is it thrown out the window for views? Allowing external code access to an objects private parts […]

HTML is domain specific

The partisans of generic media types sometimes hold up HTML as an example of how much can be accomplished without domain specific media types. HTML doesn’t have application/business specific semantics and the whole human facing web uses it, so machine clients should be able to use a generic media type too. There is just one […]

Media types and profiles

Opponents of API versioning using media types often suggest that media type proliferation is a cause for serious concern. The implication is that the more media types that exist, the more different formats intermediates and tools will need to understand in order to be useful. Fortunately, this is just not true. Having lots of media […]