NARWHL Maturity Model

With the need for rapid development and to develop a minimum viable product as quickly as possible, it may not be practical to immediately implement every recommendation made within the NARWHL framework. With that in mind – and borrowing a page from Leonard Richardson – a phased approach toward complete NARWHL maturity may be followed.

Level 0 – Nouns As Resources With Hyper Links

This is the “sine qua non” of the NARWHL framework. All of the “nouns” in your system must be normalized as much as can be considered reasonable and accessed using the endpoint formats defined here. If the amount of data returned by any single endpoint seems excessive, consider extracting any data not required by most use cases into a separate but related resource. For example, the Manufacturer data associated with a product may contain additional data – the manufacturer’s address, their SIC code, etc. – that really don’t belong bundled along with the Product resource. In this way, the manufacturer for a given product may be accessed using


Level 1 – NARWHL-JSON format

At Level 0, the response may take any form most comfortable to the API developers. At Level 1, however, we recommend applying a more rigorous JSON format that places the resource-specific data at the top level and includes consistent formatting for “_links” and “_embeds”. This also implies the use of the Zoom/Embed pattern to reduce the number of API calls and provide the client developer with greater control over the data returned within each response. The NARWHL-JSON format has been designed with these features in mind, but it may be replaced with any equivalent standardized format that serves the same purpose.

Level 2 – Content Negotiation

At every level, the MIME type of the response should be specified, even if it as generic as “application/json”. At Level 2, custom MIME types should be defined, documented and their formats enforced internally across all connected APIs. This will ensure a consistent interface for client developers and should reduce confusion across multiple API implementations.

Level 3 – Resource Profiles and Request Definitions

The final level of maturity comes when all requests and responses are fully documented in such a way that client code may automatically traverse and discover functionality throughout the entire API.

Leave a Reply

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