what method to use when link objects use operationRef

[dret]

i may just not be able to find it, but it seems to me that when link objects use operationRef (instead of operationId), it is not specified which method to use for the request? i am looking at the examples ar https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#operationref-examples and wonder how an actual request would look like. i don't know how to figure out which method to use.

[MikeRalphson]

The operationRef is a reference into an OAS document which points at an operation object. The key of that object (the last component of the operationRef) is the HTTP method to use.

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: '#/paths/~12.0~1repositories~1{username}/get'
    parameters:
      username: $response.body#/username

here the method is get.

[MikeRalphson]

@dret does this answer your query?

[dret]

not quite, but thanks for looking into this. i am still wondering: clients are expected to parse the URI and extract the last component of the path in the fragment identifier? if that's the logic they're supposed to use, that should be documented. if there's a different way (this way seems sort of brittle and not easy to implement, in particular given that the URI syntax has no concept of paths in fragments identifiers, and thus URI parsers wouldn't help with implementing this), that should be documented instead.

[MikeRalphson]

It's not the URI format which dictates the way fragments are interpreted. As I'm lead to understand, it is the mediatype. Here that is (effectively) application/json so JSON reference rules are used.

It is the tooling interpreting the OAS document which needs to parse and follow the operationRef (not a runtime client interpreting a response), so it is relatively simple for that tool to recognise it has reached an operation object where (in this case) get is the last component of the ref - and thus the method to use.

[dret]

On 2018-10-27 12:40, Mike Ralphson wrote: It's not the URI format which dictates the way fragments are interpreted. As I'm lead to understand, it is the mediatype. Here that is (effectively) |application/json| so JSON reference rules are used.

very true. but then you have to parse the fragment identifiers themselves. btw, there are no fragment identifiers defined for JSON, so what you're referring to here is the way in which OpenAPI defines and uses them.

It is the tooling interpreting the OAS document which needs to parse and follow the |operationRef| (not a runtime client interpreting a response), so it is relatively simple for that tool to recognise it has reached an |operation| object where (in this case) |get| is the last component of the ref - and thus the method to use.

ok. maybe i was misled by my hope that OpenAPI would not be as closed as it seems to be: you can only link to other OpenAPI descriptions, and not to other URIs out there that may not be described by OpenAPI. anyway, maybe i was misreading this because i hoped to find something that resembles actual hyperlinking. i suggested a small tweak to make the text a bit easier to parse, but i think now i finally do understand how the mechanism works. thanks!

[MikeRalphson]

Thanks for the PR!

[handrews]

Sounds like there was a PR and this was resolved - closing.