Link to operation mapping

[gentlewind]

Link stands for a relationship from one resource to the other, not an action between them, for example, from a book store resource to a book collection resource. With the relationship, the client actually can do more than one operations, i.e., get books (GET), add a book (POST), etc. Thus, link to operation is not one-one mapping, but one-to-many mapping.

In OAI's Link Object, I see operationRef or operationId is a singular attribute. This seems like not fully comply with the link relation's original intention.

[darrelmiller]

@gentlewind Yes, a link represents a relationship between two resources. However, it is important not to interpret the term "relationship" too strictly. RFC 5988 provides a lot of flexibility in its definition.

Link relation types can also be used to indicate that the target
resource has particular attributes, or exhibits particular
behaviours; for example, a "service" link implies that the identified
resource is part of a defined protocol (in this case, a service
description). https://tools.ietf.org/html/rfc5988#section-4

You are also correct that link relation types should ideally be usable in more than one context. However, there is a distinction between link and link relation type (aka the rel). A link that is defined in an OpenAPI definition is more like a link instance. I have theorized that the key used to identify the link in the operation definition could be a link relation type. However, it may be better if we actually add a 'rel' property to the link.

Link definitions can be placed within the components section and referenced in different operations. This would allow you to effectively define the behaviour of a link relation type and then create link instances in multiple operations.

Would this address your concerns?

[gentlewind]

@darrelmiller , thanks for your answering. It's nice to define links independently and late bound to operations as link instances. The other use case that shall get benefits from this is, in a resource response, there could be multiple links with the same rel name. Some popular media types support this scenario. For instance, in HAL (hypertext application language), a link object's key is the rel, and its value could either be a link object or an array of link objects. We would love to see this flexibility in OAI.

[danballance]

Thanks for raising this @gentlewind. I am using HAL and I am not currently able to easily express the scenario where the "rel" refers to an array of link objects. OAS3 is a big improvement over OAS2, but there are still some gaps and I believe this might be one of them.

[darrelmiller]

Having a rel property would allow you to have multiple links with the same link relation type, but a different name.

I have so many thoughts about this and not nearly enough time to write them all down. JSON HAL allows multiple links with the same name, but provides no way to identify them The original XML version of HAL did, because I asked Mike Kelly to add a name attribute to link so that you could differentiate them.

But if you do that, you risk introducing out of band coupling between a client and those link names. Formats like JSON Home from Mark Nottingham don't allow multiple links with the same rel value in a resource. I believe part of the reasoning being, how does a client differentiate between them. If you really want to have multiple, then point to a resource that is specifically a collection of those things.

I do think it is definitely worth having a thorough conversation about the value of adding a rel property.

[gentlewind]

Good to know. At anywhere, the rel name is the primary key to identify a link type. Which other link attributes can be used as the secondary key is up to the media type. JSON Home is a specific media type to describe API home, and I am not surprised it does not allow repeated links;-)

In general, I agree a collection would be primary design principle if there many objects with the same link type. However, it's still useful to have links with the same rel name in some real world cases, when the count is small, typically 2 ~ 5.

[handrews]

JSON Hyper-Schema allows multiple links with the same rel (it may be one of the few that does, apparently?) Our assumption is that, in terms of rel driving the semantics of the link, if you have multiple links with the same rel then they should be treated the same. There's no clear mechanism of distinction that makes a lot of sense, or at least not that we've found so far.

You may end up using the target and/or context URI to distinguish them (or even target attributes like title, although I'd advise against using human-oriented fields for machine processing), but that doesn't change the information imparted by rel.

Note that in draft-04, people used this to repeat links separately for each HTTP method. This was not the intended model and not the use case for the feature.

[handrews]

This scale of change is best discussed in Moonwalk (and can be backported if relevant and we decide to keep the 3.x line going). Closing in favor of:

• Improvements for links in v4 sig-moonwalk#58
• Resource oriented sig-moonwalk#30