I’m trying to build a REST API using the JSON API spec, and am finding it difficult to properly make it discoverable what the client can and should do. My rule of thumb is that a REST API should make it possible to write a generic sandbox HTML client on top, that can be used by a human to interact with it. So all actions and how to perform them need to be discoverable, but the sandbox itself doesn’t have to understand what it all means, just facilitate the interaction.
My first problem is the following. The model is users and videos, users can like/dislike/unlike/undislike videos. If a video is at /videos/123 and the requesting user has NOT liked the video already, then it should include a relationship to /users/abc/relationships/likes in an included resource of type “viewer” (representing the users relationship with the video). I had to then add meta to the link with “allow”:[“POST”] so the client can know that it’s possible to post to this likes relationship.
So far so good. But how would a generic sandbox client be able to know that the target relationship is a many relationship, and not a to-one relationship, in order to send the correct JSON? Would you solve that with more metadata, or a profile, or something else?
The obvious workaround is to have the sandbox first do a get on the relationship, where it can find out it’s a many relationship, but it would be great if this can be done in one call instead of two.
This is the first problem I attempted to solve with regard to writes in the API, and it’s already a headache. Are there already solutions to these seemingly trivial issues documented anywhere?
Any insights would be most appreciated!