Noun As Resource With HyperLinks: NARWHL

There seems to be a constant, healthy debate happening throughout the API community on what REST is and how best to implement it. This is great – as better ideas come to the fore and standards begin to settle, RESTful APIs will become stronger, more efficient and easier to use.

Watch Rob Z. Introduce the RESTed NARWHL at Gluecon 2014

But the folks implementing these APIs who are not necessarily part of this community are left in a world of confusion, mixed ideas and half-baked best practices that have never made it to the wild. They don’t have time to get sucked into the debate – they need to implement an API.

NARWHL is intended to address this audience. Where REST is an architectural style for APIs, NARWHL is a framework intended to provide a roadmap for those needing to implement an API using current best practices but flexible enough to grow into the future.

This site contains a set of API design recommendations you can implement today with the confidence that your API will be RESTful (level 3 according to the Richardson Maturity Model) and able to adapt to future iterations while still making it easier for developers to use.

NARWHL itself can get incredibly complex, recommending some implementation details (such as response definitions and content negotiation) that are not currently widely implemented. Not every detail must be implemented in order for your API to be considered “NARWHL-compliant”. You can use the NARWHL Maturity Model to create a sane roadmap to implement your API that takes advantage of the best ideas now while still allowing the flexibility to iterate on future revisions.