Supporting typed links

[dret]

it would be useful to support general web-style type links, i.e. links that use RFC 8288 link relation types, as part of API description. this could be for something like service-doc, home, RFC 5005 style versioning links, and so forth. it simply would be helpful to reuse the established vocabulary for linking between web resources. in terms of where to put this, a good place might be either the openapi object or the info object. i'd propose to add a weblinks member which then would be a map of link relation types and target URIs.

[handrews]

@dret I'm trying to understand how this would fit in the top-level or info objects. Would this be for links that are expected to be present on every response? What about links that are present only on some responses?

Note that with $schema support being added in OAS 3.1, per-response (or per-representation) links could be expressed using Hyper-Schema's links and base keywords. Although whether Hyper-Schema is the right approach here is a topic that has only come up in passing, given that Hyper-Schema is not broadly implemented even outside of OAS.

[dret]

if you're designing a hypermedia API (which of course is a huge "if" and not the case for the vast majority of OpenAPI-described designs), then for each message there is a possible set of links that may appear at runtime. that's very relevant info at design time as well, so that i know what to prepare for. so the goal would be to have design-time info about links that a message might contain, and then at runtime these may or may not be present. to my mind, this is much more design-level info and would be useful on the API description level. i am not sure that anytime soon we can depend on people using fully hypermedia-enabled schema languages. so for me, to add the most crucial bit about hypermedia, it would be great to have this being represented at the message level (and not buried in the schema). or, as proposed above, we could even be more generalized and simply expose the kinds of links to be expected. in terms of web-linking, this would be a list of link relation types. ideally, each type would be documented for the API, and then back-linked to the messages where it might be used. that way, all we need in OpenAPI is the ability to represent this list.

[handrews]

@dret I was going to ask how that differs from the existing OAS 3.0 Link Objects, but then I looked and sure enough there is no place for RFC 8288 link relation types 😮

Since the Link Objects are themselves entries in an object, I suppose the names in that object could be treated as RFC 8288 link relation types, but that is not made explicit anywhere.

[dret]

On 2020-01-20 16:01, Henry Andrews wrote:

@dret https://github.com/dret I was going to ask how that differs from the existing OAS 3.0 Link Objects, but then I looked and sure enough there is no place for RFC 8288 link relation types 😮

link objects are an abomination, and their name has so many implications that they cannot deliver on. they do extremely little, and yet their name seems to be sufficient for many to say "look, OpenAPI is supporting hypermedia now."

Since the Link Objects are themselves entries in an object, I suppose the names in that object could be treated as RFC 8288 link relation types, but that is not made explicit anywhere.

maybe. i am really not interested in link objects, they are weird and limited and have nothing to do with hypermedia. but yes, they do confuse people and whatever might be happening with actual hypermedia support would have to address this confusion.

[handrews]

@dret to be fair to OpenAPI, they have repeatedly been clear that they are not attempting to support actual (meaning runtime) hypermedia.

Agree that the naming of Link Objects vs RFC 8288 links is a point of confusion, although that's probably an OAS 4.0 topic given the degree of change involved. I mostly brought up JSON Hyper-Schema because it could be experimented with in OAS 3.1, even though OAS 3.1 will not officially recommend or endorse it.

[dret]

this has been dormant for a long time but we just ran into another scenario where it would be nice if OpenAPI had a way how to cleanly use typed links that link from the OpenAPI description to related resources. it doesn't feel like it would be a huge work item, in my mind it simply could be an addition to the info object. @darrelmiller, what do you think?

[lornajane]

Is #1034 a similar request? Would we need more than just an array of links to meet this use case in your opinion?

[dret]

On 2024-02-24 22:07, Lorna Jane Mitchell wrote:

Is #1034 https://github.com/OAI/OpenAPI-Specification/issues/1034 a similar request? Would we need more than just an array of links to meet this use case in your opinion?

the original issue was about supporting web-style links. on the web, links typically have a type. for OpenAPI, for example, how could i add the following links to an info object (using HTTP notation here):

Link: ; rel=service-doc, ; rel=license

and in general it would be great if the web's idea of typed links would be supported by OpenAPI whereever links are used (such as for example in the Link object as well). it really is one of the fundamental aspects of how the web works.

[handrews]

@dret see also

• OAI/sig-moonwalk#30

By coincidence I just added a comment about a system I worked on a decade ago, in part because it used something closer to web links, and kept them separate from operations (although there was a shorthand that combined them for certain cases).

With OAS 3.x it's a bit awkward to put link relation types in because the OpenAPI Link Object is operation-specific rather than resource-specific.

[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:

• OAI/sig-moonwalk#58
• OAI/sig-moonwalk#30