Versioning your API is terrifying. If you push out a “breaking change” – basically any change that runs counter to what client developers have planned for, such as renaming or deleting a parameter or changing the format of the response – you run the risk of bringing down many, if not all, of your customers’ systems, leading to angry support calls or – worse – massive churn. For this reason, versioning is the number one concern among the development teams I work with when helping them design their APIs.

The traditional way of handling versioning in REST is to apply some version number to the URL – either in the domain (i.e. apiv1.example.com/resource) or in the resource path (api.example.com/v1/resource). Non-breaking changes are frequently pushed out without much fanfare aside from a changelog posted to a blog or an update to the documentation. Breaking changes, on the other hand, require excessive testing, customer hand-holding, voluminous communication and a high level of planning, code maintenance and creative routing as you bend over backwards to ensure your customers can continue to work smoothly while you delicately push out a new release. With all that, everything can still go wrong.

Most API producers handle these issues by placing tight restrictions on their development teams regarding when and how the API may be updated, leading to convoluted policies that often confuse client developers and confound innovation and iteration. For example, Facebook recently described their new versioning strategy for their Marketing API. In the old days, Facebook was rather cavalier about pushing out breaking changes. “Move fast and break things” worked fine for them, but annoyed the developers who relied on their API. Though they have apparently learned their lesson, their solution to versioning – which, to be fair, is common among RESTful API providers – prevents their API from taking advantage of continous releases and forces their client developers to assiduously watch for announcements about new releases.

There’s a better way.

Continue reading →

I’ve had some trouble properly articulating my ideas around this in writing, largely because it requires quite a few jumps in knowledge and logic to understand where I’m coming from on it.

The annual RESTFest conference gave me a chance to better articulate it. In short – to understand how an API client may be able to consume a descriptor language to parse anything you may throw at it in terms of a response, consider how the browser handles plugins.

Better yet, watch my talk at RESTFest for full details:

And here are the slides on Slideshare:

I introduced the RESTed NARWHL at Gluecon 2014 on the main stage. That video is now up on Youtube, but you can view it here:

The slides are here:

I officially revealed the NARWHL framework to the world at last week’s Gluecon in Broomfield, CO. To say I was nervous is an understatement. This was the first time I’ve delivered a technical talk – particularly one where I’ve voiced so many firm opinions – before my technical peers. I know and respect many of the people who were in that audience and understood that any criticism they delivered would come from a place where they want to be supportive. But, because of the passion felt by so many in the RESTful community, I did expect this criticism to be rather harsh.

Boy it feels good to be wrong.

In fact, a majority of the feedback I got back was in the vein of, “Finally!” The RESTful API community is full of great ideas – many of which are practical and move the design and usage of APIs forward. But there’s also a lot of dithering and debate. It seems that many are more than willing to declare something as “not RESTful” before they;re willing to sit down an tell you their idea of the “right way” to develop a RESTful API.

This has left many development teams tasked with implementing a RESTful API in the lurch. They are either unable to find definitive guides telling them exactly what to implement, or they find themselves caught up in the debates with no implementation to show for it. To have someone come forward and say, “implement this and you’ll be fine” came as a source of salvation to many in the audience – many told me they couldn’t wait to get back to their teams to share this so they can move forward.

To be clear – the goal of this framework is to provide clear guidelines to implement an API that adheres to existing best practices while remaining flexible enough to allow for iteration when those best practices change or different standards emerge. Calling it a “framework” rather than a “standard” is intended to imply that you can deviate from it to a degree so long as the basic tenants of flexibility and adherence to the REST architecture are upheld. If you follow the guidelines here, adjusting them only to the specific expression of your API, you’ll still be creating something developers will be happy to build on while keeping your own team sane when the time inevitably comes to make changes – even drastic ones.

These themes struck a major chord with the people in attendance at Gluecon – I hope they also strike one with you. I welcome your feedback and would like to hear more about the challenges you may be facing while implementing your API program.

I’ll be speaking at Gluecon next week on the morning of May 22, where the RESTed NARWHL will be officially unveiled. If you’re there, I’d appreciate your feedback!