Links issues

[fehguy]

After a few deep dives into links, I've found--and others have pointed out many times--that there are some issues in the documentation of links.

• The href field is not documented as intended. It was not supposed to point to a target resource--rather to the location to an operation definition
• There is no way to define a different server location. During a TDC call we discussed with @lcrabb the desire to allow target servers to be defined as part of the response but we decided it would be too difficult

I suggest that we rename href to something more clear to ensure it's not confused with the target href. We clarify the purpose as a way to link to the operation instead. The reason is that because operationId is optional, it may be necessary to provide a JSON reference to locate an operation. For example:

http://gigantic-server.net/foo/bar/operations#/superDuperOperation

This will be especially (or almost solely) useful when we talk about remote definitions of operations.

I also suggest that we revisit the target server locator. We can add a server field which holds a single Server Object which we can use the same templating mechanism for. Thus we can use request or response information to define target hosts.

When we brought up the target server computation previously, we hadn't developed the templating mechanism. Now that it's baked (thanks @darrelmiller !) we should use it here.

[DavidBiesack]

1+ on clarifying that this refers to an operation. However, the example is unclear to me. In

http://gigantic-server.net/foo/bar/operations#/superDuperOperation

is http://gigantic-server.net/foo/bar/operations the uri of an OpenAPI definition? Or is it an OpenAPI document fragment that contains several remote operation? If so, this component model of OpenAPI definitions is not clear (maybe that is what we have yet to define "when we talk about remote definitions of operations.")

Instead, what about

http://gigantic-server.net/myApi/open-api#/paths/~path~to~resource/get

or some JSON path query that picks an operation by id)

http://gigantic-server.net/myApi/open-api#$/paths/*/*[?(@operationId=superDuperOperation)]

(I'm guessing at the right JSON path expression here; I'm not fluent in JSON path) Currently, there is no direct map of operationIds to actual operation objects

[darrelmiller]

I believe http://gigantic-server.net/foo/bar/operations just points to a JSON/YAML document that contains fragments of an OpenAPI definition. You could do http://gigantic-server.net/myApi/open-api#/paths/~path~to~resource/get also, with the caveat about escaping the /.

I'd rather not introduce another JSON querying mechanism. JSON Path doesn't have a formal spec as far as I know and it is overkill for most of our needs.

[DavidBiesack]

I agree we don't want to adopt JSON Pointer, but I would like to be able to access operations by operationId so that if an operation moves (for example, rename a path parameter {fooId} to {fuId}) such changes don't break any references. It's too fragile (and ugly) if we use just the ~-ified path/method. (Heck, even the operation may change, from POSt to PATCH for example.)

[darrelmiller]

@DavidBiesack I think you meant to say "JSON Path". We already do support "JSON Pointer". I agree that using OperationId should be an option. Having a private identifier that has no reason to change is very useful. Tony's proposal is to have operationId and operationRef. Once we nail down exactly how operationRef will work, that should satisfy all requirements.

[fehguy]

Sorry for the lag responding. There is definitely some room for issues in here. The goal is to represent a locator to an operation ID inside an OAS doc--with that said, I think it makes sense to restrict the reference to live "in a valid OpenAPI Specification document" so the context of path and http method can be detected.

I will modify the PR to take this into account.

[handrews]

operationRef was added in 3.0, so I'm not sure why this is still open. It seems like the servers idea did not gain traction as it was not discussed further? If still desired, please file separately or bring up in OAI/sig-moonwalk for 4.0 discussions.