We’ve got an API that is heavily informed by JSON API.
I’ve got a developer who would like us to change the response of endpoints that return a single resource to return an array, rather than a bare object. His argument is it would allow developers to use a single handler rather than wrap / unwrap.
The savings seems small, and the request seems lazy, but I’m having a hard time arguing that the semantic content is different – the semantic content of the response differs, but if you know the endpoint that produced it, they’re equivalent.
If this is supposed to be JsonAPI compliant service, if you are speaking about the /resourceName/{ID} endpoint, I would say the specification is quite clear about this being a resource object in the response. /resourceName -> [resource object], /resourcename/{id} -> resource object.
That being said…
[quote=“aah, post:1, topic:942”]
The savings seems small, and the request seems lazy, but I’m having a hard time arguing that the semantic content is different – the semantic content of the response differs, but if you know the endpoint that produced it, they’re equivalent.[/quote]
I would be careful with that type of thought process. A priori knowledge should be avoided and minimized if at all possible and reasonably feasible. It is easier to consume a service which is consistent, and requires less information to successfully integrate. You readily admit there is no semantic difference, but the request suggests there is at least a minor convenience for the calling engineer.
Disambiguating the response for the endpoint seems like a reasonable concern to me if you can’t come up with a reason not to do so in the implementation.
So at the end of the day, if it’s heavily ‘informed’ by this specification, but not compliant you’re free to do what you wish. Otherwise the answer is pretty clear by the specification.