link object language

[dret]

the link object description says:

As opposed to dynamic links (links provided in the response payload), the OAS linking mechanism does not require that link information be provided in a specific response format at runtime.

is that correct? i am still trying to decipher the spec language (which is surprisingly hard), but it seems that variable substitution does require some link information to be provided in a specific response format, or it will not be picked up for variable assignment and subsequent link computation. i am not 100% sure about this, though, as it is really hard to figure out how the links and link objects work and look like.

[ePaul]

From my understanding it is supposed that you don't need to put the link itself into the response, and also don't need to follow any specific hypermedia format (like HAL, JSON API, ...) for that. Of course you need the fields which are used in the template, if any (but if there are none, then the link is a bit superfluous).

[dret]

On 2017-03-28 02:47, Paŭlo Ebermann wrote:

From my understanding it is supposed that you don't need to put the link itself into the response, and also don't need to follow any specific hypermedia format (like HAL, JSON API, ...) for that. Of course you need the fields which are used in the template, if any (but if there are none, then the link is a bit superfluous).

but how do you need them? they are extracted at runtime, that's the idea, right? so there must be some way how those field values are extracted to populate the URI template fields. how is that done for JSON? for XML? for something else? there must be some dependency on how those field values are extracted on the format, or once again i have completely misunderstood how the mechanics are supposed to work.

[darrelmiller]

The variable expression syntax allows you to extract values from a request or response body using a "fragment" that uses the JSON Pointer style syntax. The callbacks documentation gives some examples on how these expressions are evaluated https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#key-expression

How does this work for representations that are not JSON? That's a great question. Personally, I'd like to see us move towards implementing these fragments, much like fragments are defined in URLs. i.e. they are dependent on the content-type they are pointing into. The spec currently doesn't say this, because we are still very much focused on a JSON based world. If there is a way to define this that does not commit tooling makers to a huge amount of work that would rarely be used, I would be very interested to hear it.

[dret]

On 2017-03-28 23:43, Darrel wrote:

How does this work for representations that are not JSON? That's a great question. Personally, I'd like to see us move towards implementing these fragments, much like fragments are defined in URLs. i.e. they are dependent on the content-type they are pointing into. The spec currently doesn't say this, because we are still very much focused on a JSON based world. If there is a way to define this that does not commit tooling makers to a huge amount of work that would rarely be used, I would be very interested to hear it.

i'd be more happy to help with a URI-based fragment part, if that's something you're shooting for. but i think it will be tough to do what you're trying to do with URI fragments. the reason being that URI fragment resolution varies depending on the media type, and is not defined for many. one such example is JSON, but a new JSON spec is underway so there's your chance to change this. but that would be a rather big change, and given the shaky nature of pretty much every JSON-related spec out there (JSON schema, anybody), i suspect it will be hard to simply pick a fragment scheme definition that everybody is happy with.

as much as i philosophically agree that it would be not so great to hardcode JSON into the spec for this particular feature, i have a hard time seeing a realistic path without doing that. that would make an already limited feature even more limited, but maybe people are fine with that, given the pervasiveness of JSON.

and in the end, even if you use URI fragment based expression, they will have the limitation of being targeted at a specific media type, just like your current approach. having URI fragment identification being media-type specific is one of the aspects of web architecture that may not be pretty, but that's just how it is.

[MikeRalphson]

I know xml is something of a second-class citizen in the OpenAPI spec, but it would be nice to allow xpath fragments in links for APIs that return xml. To allow for APIs which do content negotiation, would it be worth wrapping the link in something like a content object (i.e. a map of media-types)?

[dret]

On 2017-04-02 15:58, Mike Ralphson wrote:

I know xml is something of a second-class citizen in the OpenAPI spec, but it would be nice to allow xpath fragments in links for APIs that return xml. For APIs which do content negotiation, would it be worth wrapping the link in something like a content object (i.e. a map of media-types)?

that would work and would reflect the reality of the web that fragment identifiers depend on the media type.

the downside may be that the vast majority of people would probably see this as an unnecessary complication. but it's not too bad and there's a good explanation for it.

for XML, you could depend on https://tools.ietf.org/html/rfc7303#section-5 and allow relative URIs (just the fragment identifier) to identify the relevant fragment.

for JSON, https://tools.ietf.org/html/rfc7159 does not define fragment identifiers, so you may be left with what you have now: something homegrown that's not really a web-level spec. but that's how it is.

[handrews]

I'm closing this as moved to Moonwalk, specifically:

• OAI/sig-moonwalk#58

Please feel free to copy over any relevant points to that discussion.