Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

link object language #1011

Closed
dret opened this issue Mar 27, 2017 · 7 comments
Closed

link object language #1011

dret opened this issue Mar 27, 2017 · 7 comments
Labels
links Moved to Moonwalk Issues that can be closed or migrated as being addressed in Moonwalk

Comments

@dret
Copy link
Contributor

dret commented Mar 27, 2017

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
Copy link
Contributor

ePaul commented Mar 27, 2017

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
Copy link
Contributor Author

dret commented Mar 28, 2017 via email

@darrelmiller
Copy link
Member

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
Copy link
Contributor Author

dret commented Apr 1, 2017 via email

@MikeRalphson
Copy link
Member

MikeRalphson commented Apr 2, 2017

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
Copy link
Contributor Author

dret commented Apr 2, 2017 via email

@handrews handrews added the Moved to Moonwalk Issues that can be closed or migrated as being addressed in Moonwalk label May 24, 2024
@handrews
Copy link
Member

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

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
links Moved to Moonwalk Issues that can be closed or migrated as being addressed in Moonwalk
Projects
None yet
Development

No branches or pull requests

5 participants