Certainly one of the primary benefits of hypermedia is the creation of APIs which can stand up to the test of time through discoverability. One idea I’ve seen is having a root resource that documents the available resources of the API so that discoverability may start at the very first request. As far as I can tell JSON API does not spec a root resource. Has such a thing been considered? Perhaps it fits in the current spec via a singular resource which has links to other available resources? Curious for you thoughts on this.
1 Like
It sounds like you’re referring to HATEOAS. From my personal experience, I don’t think JSON API is designed to be this sort of interface. JSON API provides an interface for a client-side application to access data stored elsewhere. Rather than the server defining what business-logic a client can perform (beyond its data constraints/sanitization ofc), JSON API merely provides data to the client. From there, the client can use the data to perform whatever operations he or she may wish as long as it is within the parameters of the data model and data sanitization rules (validated by the server).
That being said, (as you mentioned) JSON API does define a notion of links which can be used to discover related information.
As far as a root resource goes, I am not convinced this is a great idea as APIs should be documented. If they are undocumented (but open to the public), you typically use at your own risk. It would be difficult to standardize root interface which auto-documents these APIs in any meaningful way.
my 2 cents.
That said, I don’t exactly follow this:
Would you care to elaborate?
EDIT: While I’m not entirely sure the HATEOAS model fits exactly with JSON API, there has been some discussion about it on GitHub.
Thank you for the thoughtful reply! I do believe I was referring to HATEOS in my original post. I suppose I thought that was a goal of JSON API, so this is an interesting perspective. This came as a response to some internal discussion my team was having. I like your point about documentation and tend to agree!
Thanks again for your thoughts 