Added rfc 019 for HATEOAS API

[ddokter]

I added a first draft for the implementation of HATEOAS for the Wagtail API. There's probably some more guidelines to add, but maybe first it's time for a bit of shooting...

[kaedroho]

Thanks for submitting an RFC! Please can you renumber this to 22?

[kaedroho]

Thanks for submitting this, and sorry for the delay in responding. I have a couple of questions:

1. Is this proposal for the public API, admin API or both?
2. The specification silently removes the "meta" section, is it proposing to remove it or was this done for brevity?

[ddokter]

Time flies when you're having fun. I kinda lost interest after last year's sprint, but hey, I just joined this year's sprint. I'll have a chat with @tomdyson shortly on this topic, so more info will follow.

[auvipy]

how about using django-rest-framework-json-api for this?

[ddokter]

I haven't checked this package(django-rest-framework-json-api) before, but see that the idea is to implement a JSON:API compliant REST API. I did a quick scan of the JSON:API project, but have no idea how viable it is. Doesn't strike me as something that is overly hip and happening in the world. I suppose it is the choice of the Wagtail core team what way to go with this, but it would require some serious study to prevent betting on a dead horse (as they say in at least some languages...).

[auvipy]

https://nordicapis.com/the-benefits-of-using-json-api/

[auvipy]

https://www.jeremiahlee.com/blog/2017/10/10/pragmatic-design-with-json-api/

[ddokter]

There is no technical objection for implementing the API according to jsonapi, but again: this is a decision that needs to be taken by the core team. So far however, no one seems to be overly interested. What I do see however, is that no big companies, nor foundations seem to be backing up the jsonapi.org effort, which is usually not a good sign.
Anyway, I'll await a decision, and am willing to do an implementation of some ore functionality in jsonapi if need be.

[auvipy]

Companies I know of:
Fitbit (internally),
Patreon,
NY Public Library,
(link: http://Hood.ie) Hood.ie,
Zalando,
It's also the default API format now in Drupal and ruby on rails and ember-data,
WeWork.

[auvipy]

this package can be helpful to achieve HATEOS using drf https://github.com/django-json-api/django-rest-framework-json-api

[auvipy]

Django REST Framework suggests JSON:API as an option to implement HATEOS using DRF. Also the examples seen in the RFC, I can relate to them with JSON:API specs. But yup the decisions are up to the maintainers.

[thibaudcolas]

Coming back to this after RFC #100, I’m skeptical this is a good fit for Wagtail core. I think the RFC should either be updated to explain why this makes sense as a core feature, rather than the theory of why HATEOAS is good.

I like HATEOAS in principle and JSON:API as a practical way to make this happen, but there just doesn’t seem to be enough interest in this to make it part of the core implementation? This seems primarily useful if you publish an API intended for others to reuse. While from what I’ve seen the majority of Wagtail implementers who set up APIs is for "their" own consumption (mobile app, headless site, other ad-hoc need).

[thibaudcolas]

If we want to demonstrate the relevance of HATEOAS in the context of Wagtail I think we should do this without relying on authorization or "write API" use cases. This isn’t a typical example, there are sites that do this but most of the CMS-driven content shared over an API I see out there seems to be read-only. There might be some form of authentication but I’ve not seen much in the space of authorisation at all.

See the 2024 headless survey, where the "admin API" improvements are ranked lowest as far as priority for Wagtail users.

[thibaudcolas]

See Wagtail API should have a browsable root URL #1921. Neat idea. I think the RFC should refer to this.

[thibaudcolas]

This should be expanded. To me that’s what would be most interesting to cover in RFC format, going beyond why HATEOAS is interesting.