Links issues

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.

[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.

[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.