Description
Collection+JSON has a neat feature that gives a JSON hypermedia type closer parity to HTML: template.
HTML has forms which help guide a client in making a well-formed request to create new resources (or other things, but for my purposes).
json-api seems prejudiced towards reads when compared to Collection+JSON. Consider if I hit an artists endpoint. How do I, as a client, know what request to make? json-api says:
Hmm, ok, I guess I can make some assumptions now: I assume I can just take the resource I posted to as my type (seems fine), but then, how do I know what attributes are required or optional for this resource? Ok fine another assumption, I'll just take attributes one for one, anything I read, I will try to write to in my POST request.
But what if a resource representation includes server-side additions the user wouldn't provide? How does the client know which ones are its responsibility to get from the user, and which will be calculated for it on the server? In other words, a read can be and very often is bigger than the write, but the only thing I have to make the write template are the read attributes. (Or, less likely but still possible, what if I need more attributes to create something that the server actually composes ultimately into fewer read fields?)
In many cases, especially in the Rails "just expose your database schema as an API" style of working, the read and write will be basically equivalent and that assumption holds without problems. But 1. a person (vs the json-api spec) has to make that judgement call on every client implementation ("I guess I can infer the write template by the attributes from the read") and 2. if they don't correspond 1:1, application level logic has to be written per client to gather the correct subset from the read for the write.
Could this be considered at least as an extension? Also, is parity with the hypermedia power of HTML the ultimate goal of json-api or no? (I mean, is json-api about making json-api a true hypermedia type?)