1

The HAL specification says:

Note: If you're unsure whether the link should be singular, assume it will be multiple. If you pick singular and find you need to change it, you will need to create a new link relation or face breaking existing clients.

Does making a link with a particular rel singular or multiple only apply to the use of that rel within a particular resource-representation, or does it apply to the use of that rel in any resource-representation?

For example, if I have decided that links under the item rel should always be multiple inside some resource X, does that constraint only hold for resource X, or will it also hold for resource Y if I happen to use item there as well?

Vivin Paliath
  • 94,126
  • 40
  • 223
  • 295

1 Answers1

3

Link relation types are defined independently to resource representations. In fact regularly they are defined independently to media type so that they can be used across media types.

Also be aware the link relation 'item' has already been defined and standardized See http://www.iana.org/assignments/link-relations/link-relations.xhtml

Darrel Miller
  • 139,164
  • 32
  • 194
  • 243
  • I completely agree. The rel sematic should have nothing to do with the kind of representation being used. But I'm wondering about the implications of how HAL+JSON chooses to physically represent links and rels. The suggestion to create a new rel if there end up being multiple links for a rel, where originally there was just one, seems to imply that choosing a particular physical representation may require you later to create an *entirely new* relation if you don't want to break clients, *even if the meaning may not have changed*. Is my interpretation correct, or am I missing something? – Vivin Paliath Sep 25 '15 at 23:50
  • @VivinPaliath Switching between arrays and objects in JSON is a pain. The original HAL spec was for XML and this wasn't an issue in XML because the rel was just an attribute of a link element. To be honest, this I'd never noticed that line in the HAL spec. It is reasonable guidance though if you are using JSON, regardless of rels or not because of the object/array issue. – Darrel Miller Sep 25 '15 at 23:57
  • IMO it seems like abstraction leakage from the way HAL+JSON has chosen to represent links in JSON; I don't think that a new rel should be created just because you used `{}` instead of `[]` initially; the meaning of the relation hasn't changed and this wouldn't be an issue in XML as you said. You end up with redundant rels just because of JSON issues. That's why I was wondering if in the context of JSON+HAL, a rel can *always* be represented a certain way, or if that only holds for a particular resource-representation. I like the former option just for the sake of API consistency. – Vivin Paliath Sep 26 '15 at 00:07
  • I think if you end up in the situation where you have to change from `{}` to `[]`, perhaps it might be better to create a new media-type entirely rather than having a new rel. Ideally you shouldn't have to do this, but maybe it's the lesser of two evils. – Vivin Paliath Sep 26 '15 at 00:10
  • @VivinPaliath The choice of hal format for links has been debated many times and there are definitely pros and cons. However, the current format was chosen because of how nicely you can access links from within JavaScript. Personally, I always use a parsing library to access mediatypes, so I can deal with more unnatural formats. But then again I can also transparently deal with the object/array switch too! – Darrel Miller Sep 26 '15 at 00:14
  • @VivinPaliath Having said that, one of the reasons that HAL has become popular is because it can be used so naturally from JS. There are no easy answers. – Darrel Miller Sep 26 '15 at 00:15
  • Oh, I completely agree that is is quite convenient to use with JS! I guess I'm arguing from the side of "semantic purity"; it just seems strange to me that the language or representation-format ends up affecting the semantics of your representations and relations! But as with anything it's about weighing the tradeoffs and deciding how pragmatic you want to be. No easy answers, as you said! In general what I'm aiming for is consistency in my API design to minimize surprises. Regarding clients/libraries, I agree - any good JSON+HAL client/library would necessarily have to test for `{}` vs `[]`. – Vivin Paliath Sep 26 '15 at 00:22
  • this isn't actually in the spec, just in docs of the spec. I requested it be added to the spec a while back, but didn't get much traction. in a lot of examples you see a link dereferences to a url that only includes the link. ie bb:x with a curie de-refs as http://host/rels/x ... but i find it better to include the resource type the rel is on in the url to avoid conlsiions, ie http://host/RES_TYPE/rels/x – Chris DaMour Oct 17 '15 at 03:50