The NARWHL-JSON Response Format

Several API response formats already exist to help you return your data in a consistent manner, both in XML and JSON. However, the space is a constantly moving target. Had I written this a decade ago, we’d be talking almost exclusively about XML. As JavaScript’s popularity has grown, the JavaScript Object Notation (JSON) format it uses to serialize object data has emerged as an efficient and lightweight way to pass data.

Both XML and JSON define the general format of the data as its returned, but not the format. There have been several attempts to create domain-specific as well as generalized response formats with very few of them becoming true standards. As of this writing, JSON-LD is the first JSON general-purpose format to attain something close to status as a standard with its recognition by the W3C standards body.

The NARWHL framework is designed to use any response format that makes sense to the domain of your API, so long as it follows a two basic requirements:

  • Relationships between resources must be represented by links.
  • The data specific to the request response must sit at the top level of the response, not embedded within related resources.

This frees you to implement JSON-LD, HAL, SIREN or any of the other myriad existing and emerging response formats in the REST API ecosystem. However, we do add one more to the list that you may consider – the NARWHL-JSON response format.

NARWHL-JSON adheres to the two basic requirements while also trying to keep things as simple and flexible as possible.

Links are an array represented within a hash with the key name of “_links”. Each link is, itself, a hash that includes everything a client application would need to access the link – the URI (“href”), the relationship to the current resource (“rel”) and the HTTP method by which it should be accessed (“method”).

NARWHL-JSON also supports the Zoom/Embed pattern by providing a hash with the key “_embeds” containing the NARWHL-JSON representation of any requested related resources.

The NARWHL-JSON format is used throughout this site to demonstrate how most response data should appear.

One thought on “The NARWHL-JSON Response Format”

Leave a Reply

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