search

michalporeba / odis

Search in decentralised systems. Search federation, result moderation, aggregation and feedback with hypermedia in ReSTful API to round it all of.
MIT License
9 stars 2 forks source link

HATEOAS - what are the options for implementation? #2

Closed michalporeba closed 2 years ago

michalporeba commented 2 years ago

Questions

Background

Hypermedia as the Engine of Application State (HATEOAS) is the style of architecture I will want to allow the data in search to flow both ways. But I want to use it also to create better software, better developer experience to help with the adoption.

"If we can create software that people can learn as if they are solving puzzles, they will learn it faster, they will enjoy working with it, they will become more productive. I think that sounds pretty good." Dylan Beattie in his talk Life, Liberty and the Pursuit of APIness: The Secret to Happy Code

In fact, Dylan Beattie has a few talks about the problem with developer (user) experience, APIs and hypermedia in them. The Rest of ReST inspired a lot of my thinking on the subject.

"REST is software design on the scale of decades: every detail is intended to promote software longevity and independent evolution. [...] Many of the constraints are directly opposed to short-term efficiency." Roy Thomas Fielding - Architectural Styles and the Design of Network-based Software Architectures.

In his paper in 2000, Roy Fielding defined 6 constraints of a RESTful system and included the HATEOAS in the "Uniform Interface" constraint. I think it is time to get closer to the REST original idea.

Shortlist for review

HATEOAS is just an architectural style. There are multiple standards to consider.

It appears that 'modern' HATEOAS is almost exclusively associated with JSON, even though there is no requirement for it and early examples used XML a lot. It might be a problem as the OpenSearch - the standard for federated search - is XML based.

Looking at google trends, the three most popular are JSON:API, HYDRA and HAL.

References

michalporeba commented 2 years ago

Do I have to choose?

My initial idea was to provide two interfaces one for people, and one for computers. The question was what styling to apply for the human one, and what format to use for the computer one.

But is that the right approach? What if I didn't have to choose if I didn't have to do both? After all, both should expose, ideally, the same functionality. What if there was a way to generate a single response consisting of data and actions, and format the response either to a computer or human-readable format?

References

michalporeba commented 2 years ago

HAL - review

Hypertext Application Language (HAL) introduces addresses to the data and makes the API more resilient to change in URL structure and addition of new actions, however, it does not provide any way of defining the actions past their URL. That means the model that needs to be supplied, or even the HTTP method used is not specified. A custom HAL extension would be needed.

It would be easy to extend the HAL to provide links to definitions of payloads, or include them in the response as HAL is JSON based, and so any addition that doesn't conflict with the existing standard should work.

michalporeba commented 2 years ago

Siren - review

Structured Interface for Representing ENtities (Siren) is centred around Entities which can contain Class, Actions, Links and Properties.

The Siren's Class is not a type description, but rather describes the nature of the entity returned, information which is used to present it to the user. The entity classes supported by the API should be known ahead of time to the client! (Perhaps not very extensible for wider use).

Actions contain information about the fields, method and more, so forms could be constructed automatically. The field types are very close to HTML5 input types! But Siren doesn't contain the model metadata, a problem that could be fixed with a custom extension.

michalporeba commented 2 years ago

Collection+JSON (Cj) - review

Collection+JSON (Cj) is very CRUD focused, but with good support for objects, addresses and action definition, even if it might be very verbose. (Not worse than HTML rendered output at least).

The potential limitation is that it appears to support only flat objects rather than deep JSON object graphs.

michalporeba commented 2 years ago

JSON:API - review

The JSON:API style of hypermedia interface is similar in capability to Siren, as it allows for definition of objects and addresses, and also has support of actions/forms like Cj. What is interesting is that the objects are all held at the top level, and only referenced when nesting would be needed. This allows for entity reuse and bandwidth savings. Also, to help with efficiency on the transport layer, the standard supports sparse attribute requests. CURIE are not used as they are in HAL. But similarly to Cj it does support error messages.

The standard is still developed and the new version 1.1 will be published soon.

michalporeba commented 2 years ago

HYDRA - review

a vocabulary for HYpermedia DRiven Api is based on, and using internally JSON-LD. It is not a registered standard (yet) but is supported by W3C.

Hydra is also able to describe the API - an alternative to OpenAPI?

References

michalporeba commented 2 years ago

Conclusions

I will try to support multiple styles of hypermedia API, and extend the idea to supporting renderers that produce user navigable UI, perhaps all the way to the accessible, standard Design-System look and feel. The approach to usability embodied in DS supports this approach. It is all interactions.

The challenge will be to find a technical solution within Django and the Django REST framework to make it possible. There is support for custom renderers, but I am not sure at the moment that will be enough.

There are other approaches that could be extended to support Django, like ripozo but they appear to be outdated and not maintained.

If the multi-format approach is not easily achievable, I can make JSON:API or HYDRA work.