REST (or “a RESTful API”) is really just a rather loose set of constraints for creating an API spec. It’s generally left to the developer to create a custom RESTful API specification for his app. JSONAPI is a generic, evolved open-source RESTful API specification ready for use… perhaps preferable to rolling one’s own. In XML-terms, I see it a bit like a boiler-plate WSDL, minus any schema metadata.
JSONAPI makes (at least) the following implicit assumptions or assertions:
- Relational data is useful (but not required).
- POST, PATCH, DELETE and GET are semantic wrt relational data and should be used in a consistent way, which the spec defines precisely based on RESTful principles.
- Relations should not be defined between non-existent entities – therefor any entities that need to be related and which don’t yet exist should first be created using POST requests, then related using PATCH requests. (This is useful for things like apps with an off-line requirement because one can define and store these requests and then send them once online and process any entries in a granular way.)
JSONAPI benefits include:
- Libraries that implement the JSONAPI specification are available generally for most front-end and back-end stacks
- It formalises best practise in terms of how to manage and structure requests and data structures for relational data via JSON.
- Because it defines (effectively) a structural specification for transport of JSON data, it also decouples the front-end from the back-end. As long as both are implementing JSONAPI spec, you could swap out either without affecting the other. This begs the question, “why is decoupling them of value?”, to which the answer is: long-term maintenance. Frameworks come and go… sometimes a revamp is required. Decoupling FE and BE presents value in potentially limiting the scope of the revamp.
Having watched your talk on QEWD-JSdb on LNUG I took to heart what you said, which is that “80% of your work is this – moving data from JSON into some structure and sending it across the internet and marshalling it into the structure you want… and should you really be doing that?”. I completely agree with that, except that I think the figure is closer to 90% :D I see JSONAPI as an attempt to lower that percentage.
Based on my understanding of that LNUG talk, it seems to me (in loose and analogical terms) that what QEWD-JSdb perhaps sets out to achieve could be called “persistent two-way binding across the full stack”, which sounds like an amazing efficiency. Although I don’t understand how that would work from a front-end perspective in practical terms. I assume one would still need to define a RESTful API spec, in which case JSONAPI may be of benefit.
Further thoughts?
Noel