I love your passion for convention over configuration.
That said, in the the last 3 points, if you do not have any data to place into the meta object, you’d be left with a) an empty object b) the requirement to put meta: null or c) leave out the meta object
Also, the meta object may contain more than one key, which also violates your proposal
Thus, it seems these points
- The Link object should have the same output
- Easy to test/implement
- Non conditional statements for data manipulation (string vs object)
are, for better or worse, un-avoidable, or am I missing some of your argument?
Well technically the self link (in the spec) doesn’t have a meta object, the related link does. But the general definition of the meta object(which is very open and has no specifics depending on ‘where’ in a json api response its used) says:
Where specified, a meta member can be used to include non-standard meta-information. The value of each meta member MUST be an object (a "meta object").
Any members MAY be specified within meta objects.
Which means its pretty much a free for all key -> object - so good question in general I’d say, just not sure if there is a way out of that
Note: Additional members may be specified for links objects and link objects in the future. It is also possible that the allowed values of additional members will be expanded (e.g. a collection link may support an array of values, whereas a self link does not).
So self link is just a string, related have meta with count??!?!?!?!? I am lost.
I just see this as { href: '...', meta: { whatever you want } } Do I missing something?
Yeah this part is confusing I agree. That line (i believe) is saying ‘we might add to what you can put in the links object’. For example they might make to-many relationships be an array of links similar to how the data key is an array when those relationships are embedded in the ‘included’ key of the same payload. This would prevent a trip over the wire just to get the related resource object (which is what the self link inside a relationship object, like comments or author, points too) (just a guess, but i guess that’s the point, its there to note ‘this may be extended in the future, but we don’t know how yet’)
One rule of thumb that may help in general is If you dont think about the links being external (via urls) but instead write the code to handle embedded related resources first. I think it’ll be easier to reason about. At least that helped me. Once that makes sense, then you can limit the size of the initial payload at the cost of making more than one request to fetch the related resources.
Someone should have a better answer than me tomorrow I’d say, but that’s my guess.
FWIW - i just re-read the spec, so worthwhile question indeed.
Of course, allowing the string form makes responses more concise, at the expense that consumers have to support both forms. Whether that’s a good tradeoff is debatable, but at this point, the ship has sailed. That is: if we allowed clients not to support the string form now, that would break their support for APIs that are already using the string form, and JSON API has committed to not making such breaking changes. So this is a non-starter for now, I’m afraid.
but with the same output issue probably is better A
dont use it, unless you see a use case of course