In my API, I have rels that look like this:
For a single item:
{
...
_links: {
...,
"api:activities/activity-resource": {
"href": "..."
}
}
}
On another resource, I have multiple instances of activity-resource
. How should I represent this? Is the following ok:
For a collection:
{
...
_links: {
...,
"api:activities/activity-resource": [{
"href": "..."
}, {
"href": "..."
}]
}
}
It kind of makes sense since they are still instances of activity-resource
, and a human being can look up the documentation for information on how to deal with those resources. However, now my API is a little inconsistent in that in certain representations the api:activities/activity-resource
rel points to a single instance whereas in others it points to a collection.
I can make the argument a developer can figure out what he/she needs to do from the API documentation, but it helps to have a consistent API as well.
I've encountered this same weakness in the HAL spec in practice. A perfectly conforming client would treat the rel : {} format as a shorthand for rel : [{}], and so the switch form resource instance to instance should be no big deal.
but given that many HAL consumers just treat hal+json as straight json (ignoring the HAL semantics entirely) it gets worrisome. I was working with some devs that assumed rel : {} implied am N-to-1 or 1-to-1 relationship..but that was not the case. Once that bit us one time, I decided that we should always use rel : [{}] syntax if the rel could EVER be more than 1 as a hint to the consumer. We consider a change in these rel multiplicities to be breaking compatibility because of this and favour new rels over lifting a single rel to multi as that is backwards compatible...then we consolidate in the next major version.