Hypermedia and path variable

[boubasse]

Hi everyone,

I'm facing an issue an i don't know if there is a solution yet.

Is it possible to pass an absolute URI from a links object as a variable for a path ?

Example :

links:
  pathLink:
    operationId: whatever
      parameters:
        pathUri: '$response.body#_links/whatever/href'

And then having as a path :

paths:
  '{pathUri}':
    get:
    operationId: whatever
      parameters:
        - name: pathUri
          in: path
          required: true
          schema:
            type: string

According to the specification, paths must be relative but in that specific case could it be acceptable ?

Thanks for your answers.

[darrelmiller]

@boubasse No it is currently not possible and it is something we would really like to fix. I have debated doing something like you suggest but the problem is that paths only contain the path part of the URI. Some feedback we have received is that people want to be able to specify the complete URL in the input URL. This can get messy if the path matches with an existing path, but the host or query parameters don't.

Having said this, if we are able to support multi-segment path parameters #1459 then it would become possible to describe a path as you suggest.

[boubasse]

@darrelmiller It means that currently the power of hypermedias cannot be specified.
Since hypermedias usually contain absolute URI, it means that at the moment, we cannot use absolute URI for paths according to your post.
But let's suppose that we are using a relative URI (e.g. '/users/1') in the hypermedia.
Since the OAS syntax involves using a "/" to specify a path item, the result would be '//users/1'.

At least, I think it should be interesting to consider removing the slash from path.

Using relative URI in hypermedias would theoritically respect the OAS, wouldn't it ?

[handrews]

At least, I think it should be interesting to consider removing the slash from path.

Using relative URI in hypermedias would theoritically respect the OAS, wouldn't it ?

I confess I've always found the choice of path concatenation over RFC 3986 reference resolution confusing. Reference resolution has its own slightly counter-intuitive aspects, but it is how literally every other hypermedia format works that I'm aware of.

[darrelmiller]

@handrews That leading slash in paths makes me sad every time I see it.

@boubasse I don't think removing the slash is feasible in a non-breaking way. So, I think we are stuck with it until at least 4.0

However, there is another more radical thing that might be doable in a point release. We possibly could introduce a new top level concept called 'resources'. The resources node would use a complete URI Template to identify the resource. This would enable describing resources that can only be discovered via links and also enable supporting operations that are differentiated by query parameter.

resources:
  '{uriTemplate}':
    get:
      operationId: whatever
      parameters:
        - name: pathUri
          in: path
          required: true
          schema:
            type: string

This would be a big change and I don't know what the appetite for this kind of change is in the community.

[boubasse]

@darrelmiller I think it's a great idea to introduce the "resources" node.
It will help people that want to use hypermedias. Moreover, it doesn't break the actual nodes.
Hope that we will see this kind of node soon.

[boubasse]

@darrelmiller By the way, I forgot to say that it will be very useful for the 3GPP to have this kind of object/node.

[cmheazel]

If I understand this correctly, the resources node would differ from a path node in two ways:

1. The resources node URI template includes the server URI.
2. Server Objects associated with a resources node must have a server URI which matches that of the resource node.
   Is this correct?

[handrews]

@darrelmiller if you're willing to consider a resources object, it might be worth considering compatibility with JSON Hyper-Schema as it is resource-oriented. Hyper-Schema would not directly solve all of the problems here, but it might be part of a solution, or perhaps parts of the solution could match Hyper-Schema in a way that would make it easier to use them together. Should I go into that more here, file a new issue for it, or leave it alone for now?

[darrelmiller]

@cmheazel The URI template may resolve to a relative reference, in which case it would still respect the root servers object. I don't know if a resource object would have a servers object. One of the challenges of this conversation will be to decide how closely the child objects mirror those of the path object children.

@handrews Just from a naming perspective, I'm not sure if resources is the right term to use. First it clashes with a term used in Swagger 1.2, which is not wise. And secondly, URI Templates can point to an entire set of resources. I don't want to further abuse the resource term.
I would be interested in understanding how this extension to the OpenAPI spec could align with hyper-schema. There's no point doing something different if something similar works. And I see no reason not to continue the conversation in this issue.

[cmheazel]

@darrelmiller But if the URI template resolves to a relative reference, isn't that a path node? What does the resources node provide us besides relaxed constraints on the URI template?

[darrelmiller]

@cmheazel The other benefit is being about to use query parameters to differentiate between operations.

Currently with Path Item Object we can't do this:

   /report/{id}?format=detailed

   /report/{id}?format=summary

[cmheazel]

@darrelmiller Nice! I'm liking this better and better.

[handrews]

@darrelmiller OK I'll add some thoughts on Hyper-Schema here. A few preliminary points:

• If we support alternate schema formats, there's technically nothing stopping people from using hyper-schemas as schemas. I had not actually thought about this before this moment, and I'm going to have to think about what that should even mean.

• Regarding "URI Templates can point to an entire set of resources. I don't want to further abuse the resource term"- Link Description Objects in Hyper-Schema also really describe sets of links. Most systems that I've seen that use templating at all kind of gloss over this distinction, for better or worse. I'm just acknowledging the weirdness here, no solution.

• Independent of hyper-schema, it's worth remembering that URI Templates let you templatize anything in the URI. For instance, the scheme (http vs https vs coap vs coaps?) the user information in the authority (I've never seen this but someone was telling me about it somewhere), or the fragment.

[handrews]

Based on today's TSC call, I'm going to write up some best practice ideas for using JSON Hyper-Schema as an "alternate" schema format (#1532), as that seems more promising than a new top-level object of resources things. It will be interesting to consider how that fits with the OAS Link Object as the OAS Link Object and Hyper-Schema's Link Description Object overlap but are not identical.

[silkentrance]

@handrews regarding

or the fragment.

and the example provided in https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#linkObject

$response.body#/uuid

This seems to be a fragment, yes, but it corresponds to a property of the response.body which is a json object.

Off Topic:
Why this overly complex notation? Why not just $response.body.uuid? Given that it refers to a property of the response body which resembles a json object? or even $response.body[0] in case that the response is a json array and so on...

[handrews]

@boubasse @darrelmiller I am finally coming back to this, especially now that alternativeSchema will at least theoretically make it possible to share schemas between Hyper-Schema and OAS 3.1.

[handrews]

hit post too soon..

My point was to see if there's still interest in the resources idea or if anything else has come up in the meantime.