apiresthateoasrelcurie

Can a rel that uses a CURIE be used for a single instance of an item and for a collection of those same items?


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.


Solution

  • 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.