This is a case where i think this spec falls down some. There are all these REST frameworks that do the heavy lifting of binding normal HTTP parameters to variables, validating, sanitizing, and providing to the application layer. And this criteria thing breaks all of them.
If we switched to criteria[ … ] the application back-end has to parse that list, validate it, make sure it is a sane request, and then go find the right block of business logic. Whereas with a normal http parameter all of that is done for us and it is something that everybody with a little web experience can recognize.
In this case I also think a POST is a little odd. I see that a POST might fit the json-api spec but it sort of ruins HTTP in general I think. You issue a post and in the response you get a multipart message that represents a PDF? Seems like a GET to me. Additionally the body of the POST is a single piece of meta-data? Doesn’t seem right or natural to me.
I could easily be missing something about the spec but I would be curious to hear thoughts on this.
[Full disclosure: I work with Andrew on our implementation using the spec which includes some special challenges including the need to run on java 6 in the back end for the time being.]