The Need for API Guidance in REST (#humblebrag)

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.

Leave a Reply

Your email address will not be published. Required fields are marked *