Lack of Hypermedia

Justin Rohrman, a former co-worker of mine, recently posted “6 Reasons Your API is the Windows Vista of APIs.” For his article, he asked me:

I was wondering if you might give me a short description of what you see as one of the biggest API problems?

I thought it might be helpful to post my full response, which follows:

One of the most common problems I see in API development is lack of hypermedia, or none at all. By hypermedia, I mean links that describe relationships among data in the API. When hypermedia isn’t used, the API becomes brittle, and those building clients that talk to the API are forced to code to URLs. The URLs become an important interface to the API, and if they change, they break everything. This leads to URL-based versioning schemes, and the only upgrade path for clients is to modify their code to accommodate the new versions.

When an API uses hypermedia, the URLs are no longer important. Clients talking to the API do not need to code to URLs because the API will always convey where to go next through hypermedia relationships. If a URL changes, then there’s no problem. The change gets communicated through the API. This leads to a more flexible and evolvable API that can change over time without needing to update all the clients.

I gave a talk at True North PHP this year that covered this topic. The slides are available for download.