0

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.

Paul Sweatte
  • 24,148
  • 7
  • 127
  • 265
Vivin Paliath
  • 94,126
  • 40
  • 223
  • 295
  • That's exactly how HAL handles it. I think it is a reasonable approach. – Darrel Miller Jan 30 '15 at 19:31
  • Yeah, it looks like it is according to spec, but I anticipate fielding questions about consistency, as to how it is an array of links in one case, but a single link in another. I guess I can say "read the docs!", but I was wondering if there was a way to disambiguate this in some manner, since you don't end up with this ambiguity in the XML representation. – Vivin Paliath Jan 30 '15 at 19:34

1 Answers1

1

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.

Chris DaMour
  • 3,650
  • 28
  • 37