The Definition Endpoint
One of the goals of the NARWHL framework is to develop APIs that are as automated as possible. Discoverability and dynamic client generation are both key to making this possible.
To do this, however, every resource should be responsible for defining what can request and should expect in the response. There are several formats that exist and are emerging to describe resource profiles, such as I/O Docs and RAML, but those details are covered elsewhere on this site.
Systems supporting these definitions should also support a consistent way for the client to find them. The “definitions” endpoint is one way the NAWHL framework supports these. For example, calling
Should respond not with the representation of the requested resource, but with the definition of the resource itself. Similarly, requests to all resources should include a Link in the response header back to the definition for the resource. For example, a call to the resource URI
Should respond with the expected representation of the resource, but the response header should include
Link: <http://api.example.com/v1/products/definition>; rel=”service”
The “service” relationship is borrowed from the ATOM publishing protocol, where it serves a similar purpose.
The definition for a resource may also be obtained by using the HTTP method OPTIONS, so that a call to
would return the same definition document as a call to
The reserved “definition” endpoint exists to serve those clients and server that are not able to use the OPTIONS method.
The Views Endpoint
The goal of any successful API is to make it easier for client developers to create applications with it. With that in mind, there will be situations where custom “helper” endpoints may be required to present views of data that are more helpful for developers to access. For example, if a developer is logged in on behalf of a Store Admin and they want to pull a report displaying the most popular items currently being sold, the system may compile this automatically on the back end and serve it from the URI
The “views” endpoint separates these custom endpoints from the rest of the URI structure and indicates that the representation being returned is not a resource, but a specific view of that resource. These views may contain information compiled from other resources as well to create a more efficient response.
Caution must be taken when creating custom endpoints. Before creating them you should first try to access the data you need through standard calls and, if necessary, using the Zoom/Embed pattern. Creating too many one-off custom views can lead to an unmanageable and unwieldy API.