SimpleHAL is an implementation of the HATEOAS concept. HATEOS provides useful features to the client of a ReST app:
- Discoverability
- HATEOS allow the developer to learn how an API works by example. The API documentation may not mention subtleties of the implementation, details of the API may change without notice, or there may be no documentation at all.
- Knowledge Export
- HATEOS exports knowledge of a ReST service's API to the client. This simplifies the client because it does not need to embed knowledge of how to use the API.
- Resource Style
- HATEOS nudges the API towards a resource-based style. This means that the API provides unique, permanent links to resources available from the API. For example, a movie will always be represented by only one link and that link will always refer the same movie.
The HAL Draft IRC is a concrete specification of the HATEOS concept.
There are several examples of HAL public APIs available, including a nice one by Rotten Tomatoes.
Various implementations do not follow any common standard. The RottenTomatoes API has its own format, as did the Netflix API (resquiat in pace).
There are a few proposals and implementations for a common standard.
The IETF HAL proposal is the only one I found that includes support for collections of items, not just top-level links. _linksare top-level links and _embedded are collections.
Also, the Spring HATEOS project uses the HAL format.
The examples in the IETF draft allow the HAL blocks to contain information that is not in the outer blocks. SimpleHAL does not implement this aspect. A basic premise of SimpleHAL is that the HAL blocks are optional add-ons to the base JSON object, and so they cannot contain information which is not present in the original response.
HalBuilder is a set of libraries for creating data in the HAL format for several Java-based languages.