link object scope

[dret]

am i correct to assume that currently link objects are just per response? if so, i am wondering if it might be useful to be able to support a different scope for link objects? for example, it might be useful to be able to easily say that a home link (proposed in https://github.com/mnot/I-D/issues/41 and documented at https://mnot.github.io/I-D/json-home/#link-relation) should be considered present in all responses. this would complicate the processing model because then the effective response of an OpenAPI -described API would be the union of the received response, plus all added link object links that apply to the context of the response. but it would be a rather powerful to support hypermedia in a way that allows OpenAPI to support links without requiring them in all responses.

[tedepstein]

@dret, I don't believe there is currently any way to specify links at the path item or API level. It's strictly response-level for now.

However, you can define reusable Link Objects in /components/links and reference these in the response links.

this would complicate the processing model because then the effective response of an OpenAPI -described API would be the union of the received response, plus all added link object links that apply to the context of the response.

Note that inclusion of links has no effect on the actual response payload or response headers. Links are design-time metadata, providing information that clients can use to present and/or traverse links to other resources. The client must have access to the OpenAPI document (or to some link-aware artifact generated from the OpenAPI document) in order to comprehend these links.

Each link is defined by a runtime expression that can include static text and/or references to information in the request or response.

You're right to say that allowing links at API-level, path-level or method-level incurs some added complexity. But that complexity would fall on the client, who has to collect the full set of applicable links from all of the containing contexts. It wouldn't have any effect on the response sent from the server.

[dret]

On 2018-05-29 17:48, Ted Epstein wrote:

@dret https://github.com/dret, I don't believe there is currently any way to specify links at the path item or API level. It's strictly response-level for now.

ok, in that case it's how i thought it is.

However, you can define reusable Link Objects https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#linkObject in |/components/links| and reference these in the response links.

true, but then you'd have to reference these objects from all responses individually, creating a lot of redundancy.

but i could at least envision some kind of OpenAPI viz that would allow me to easily find out from which responses a reusable link object is referenced.

this would complicate the processing model because then the
/effective/ response of an OpenAPI -described API would be the union
of the received response, plus all added link object links that
apply to the context of the response.

Note that inclusion of links has no effect on the actual response payload or response headers. Links are design-time metadata, providing information that clients can use to present and/or traverse links to other resources. The client must have access to the OpenAPI document (or to some link-aware artifact generated from the OpenAPI document) in order to comprehend these links.

yes. to me, this was an odd thing to be added, but since OpenAPI went that path and introduced this ability to have "design-time" and "runtime" information that effectively could be considered the "full API response semantics", one could now explore how to use this facility a bit more effectively.

the "home" example i gave would be one good candidate for this. one could even envision fancy intermediaries injecting runtime info at design time to minimize runtime volume, and still allow clients to get the "full" responses on the client side.

Each link is defined by a runtime expression https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#runtime-expressions that can include static text and/or references to information in the request or response.

yes, but that's how the link target is computed, right? it doesn't make the link source any more flexible, or am i misunderstanding it?

You're right to say that allowing links at API-level, path-level or method-level incurs some added complexity. But that complexity would fall on the client, who has to collect the full set of applicable links from all of the containing contexts. It wouldn't have any effect on the response sent from the server.

yes. actually, it would make it easier for services to define and implement APIs, if they follow hypermedia principles. but it then would depend on the clients being OpenAPI-aware, and it would introduce the more complex processing model of how to compute effective responses on the client side.

[tedepstein]

Each link is defined by a runtime expression that can include static text and/or references to information in the request or response.

yes, but that's how the link target is computed, right? it doesn't make the link source any more flexible, or am i misunderstanding it?

I don't think you're misunderstanding it. Runtime expressions are only used in the parameters and requestBody of a link. (They're also used as keys in callbacks, but that's out of scope for this discussion, I think.)

Runtime expressions don't affect the link source; i.e., they don't specify a scope for the link. That scope is always a single response where the link is declared.

Runtime expressions only affect the link target. And runtime expressions are still limited, even in their ability to specify the link target:

• The target must always be an operation, not a path item (which could have multiple operations), nor an arbitrary resource identified by a URL.
• The URL of the target is determined by the Server Object specified in the link, plus the relative path (key) of the Path Item that contains the target Operation. That Path Item can use path parameters, which can be resolved by runtime expressions. The Server Object's url can have Server Variables, but these are not resolved by runtime expressions. Server Variables are determined by the server, presumably on startup. AFAICT, OpenAPI doesn't specify Server Variable resolution; it's implementation-defined.

[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