Page History

On its own, information represented in resource objects is simply media. However, in order to encourage client exploration and access to related resources we need to add hypermedia to our resources. RESTful API developers often abandon hypermedia (the "H" in HATEOAS) implementation because it can be considered more effort than it is worth. The SRP HTTP Framework makes this much easier through the use of automation and dedicated services.

...

The previous services enable developers to add hypermedia that follow the HAL specification (specifically the _links and _embedded reserved properties). While the URI relations that are defined by the _links reserved property provides these URI relations provide valuable hypermedia to the client, many developers have expressed a desire for additional metadata that will better inform the client to better instruct clients how to interact with the URI. call the URI. For example, a URI by itself doesn't inform the client which HTTP methods are supported. Granted, the OPTIONS method is intended to provide this information, but other requirements might necessitate out-of-band knowledge. This causes our APIs to lose their self-documenting character.

Mike Kelly, the author of the HAL specification, comments that omitting additional metadata in the HAL specification was "intentional" in order to keep it "focused on linking". However, he also suggests that "HAL is therefore a good candidate for use as a base media type on which to build more complex capabilities". This has spurred developers of RESTful APIs to shore up this gap through alternative hypermedia types (such as api+json, collection+json, hyper+json, and siren+json). Unfortunately, none of them have the maturity and broad acceptance that HAL does. Also, some of them require too many complexity in order to add simple hypermedia to the resource. HAL, on the other hand, is relatively lightweight and easy to implement and consume.

Therefore, the SRP HTTP Framework uses the HAL specification as its base media type. The AddLinkRelationship, AddEmbeddedResources, and GetDatabaseItems services produce HAL compliant hypermedia. However, in those cases when a developer really wants to provide extra metadata to the client, we have provided the AddFormAction service. The AddFormAction service adds a custom hypermedia structure inspired by the work Ben Greenberg and his team did for the Comcast Xfinity APIs (you can watch his presentation on this here).