Variables/Parameters in Links

[LukasRos]

The OpenAPI v3 links feature allows specifying related operations. To me, however, the spec was not clear on whether it's possible and if, how to define links that require an additional variable for the call.

To give a practical example, assume there's a GET /users operation to list all users and a GET /users/{id} operation to get details about an individual user. I could add the latter as a link to the former but this link requires an additional piece of information, specifically which user from the list I want to receive details for.

{
 "links" : {
  "details" : {
   "operationId" : "getUserDetails",
    "parameters": {
     "id" : "$response.body#/*/id"
    }
   }
  }
}

Is that possible or even desired to express with the links feature? If yes, is * the right syntax for a placeholder in JSON pointer? If not, is there another way?

[darrelmiller]

From a spec perspective, the JSON pointer with a * is not valid. While defining the links capability there was no attempt to define a mechanism to that would declare a set of links based on the assumption that a response contains a set of similarly structured objects and a client is likely to select one of those objects.

This scenario is definitely something that I have done using explicit hypermedia, but I'm not sure how feasible it would be the static links design in OpenApi V3. JSON pointer doesn't support returning a set of nodes. But JSONPath does. However, even once we are able to reference the set of potential parameter values, we still need a way to parameterize it to be able to select a particular parameter instance.

It's an interesting idea and one worth exploring more, but we need a way to indicate that a link parameter requires further client input before being resolvable.

[LukasRos]

Ok, thanks for your quick reply and the clarification, so I've understood links are always 1:1 pointers to other operations, never 1:n. I think that 1:n links with variables are a really interesting feature and would love to see them in a future version of the OAS.

[ralfhandl]

We also have the "get (filtered) collection/get single item within collection" pattern in almost all of our APIs, and it would be helpful to link the operations in that pair in a machine-readable way beyond naming or URL conventions.

[handrews]

I may annoy @darrelmiller by jumping in with this, but JSON Hyper-Schema can express this sort of thing as of draft-06, and better in the soon-to-be-published draft-07.

Of course, nothing implements recent hyper-schema drafts, it will be some time before I put out a reference implementation, and it doesn't have anything remotely resembling the ecosystem of OpenAPI. But... if anyone's looking for ideas, we've at least thought about this issue a lot.

[tgockel]

In #1452, I suggested JSONPath, which solves the same "identify pattern of things" problem. The advantage is that it should feel familiar to XPath users, so it should be too offensive to those dealing with XML data.

[darrelmiller]

The challenge with JSONPath is there is no detailed specification to ensure consistent implementations.

[handrews]

@tgockel @darrelmiller in Hyper-Schema, we avoided JSON Path by attaching links at specific locations within the schema (mapping to corresponding instance locations). So attaching the link under an items makes for a link attached to each element of the instance array that items describes.

Then we used Relative JSON Pointer to adjust variable resolution upwards or downwards. This is simple and unambiguous.

With JSONPath, in addition to the lack of specification, wildcarding really returns sets of data, and then you have to correlate your "current" location with the location within that set. Which is solvable but increasingly complex the more deeply you nest things.

Relative JSON Pointer solves this by starting from the most specifically nested thing, so that going "down" from that point does not require wildcarding, while going "up" keeps you in the correct subtree without having to calculate things.

It's a really complicated problem involving being able to set the attachment point of the link and independently set its context to potentially a different location than the attachment point, and independently set the resolution starting point of every template variable. And handle cases where the location you want to resolve from doesn't exist. We basically spent a year on this spread out across draft-06 and draft-07.

An example of different attachment point vs context is the "item" link relation, where it needs to be attached to the individual array items, but the context is supposed to be the entire collection, not the single array element within the collection.

[MikeRalphson]

I was idly wondering if we could resolve one simple case of this issue with some guidance in the specification:

If the link parameter expression resolves to an array, and the target parameter is itself not an array, then any item(s) from the source array MAY be used to provide the target operation parameter value.

This would handle the case of a simple array of resource ids, but not an array of resources containing ids (this could be accommodated by providing an additional itemExpression - but that's getting messy) . I appreciate that a more generic solution would be infinitely preferable.

The wording above is just to get a feel for the idea.

[darrelmiller]

@MikeRalphson That is a decent solution for expanding an array of ids into an array of links. I fear the much more common case is the array of objects where each object has an Id.

It will be interesting to see if we get alternateSchema working if a hyper-schema could be used to achieve this goal.

[handrews]

@darrelmiller

It will be interesting to see if we get alternateSchema working if a hyper-schema could be used to achieve this goal.

I think this will be possible. I'll keep this use case in mind.

[chatelao]

Any progress welcome. Here a 1:1 pet sample as a first contribution:

      # Link pets -> pets{petId}
      # -----------------------------------------------------
      links:
        ShowPetByPetId:   # <---- arbitrary name for the link
          operationId: showPetById
          # or
          # operationRef: '#/paths/~1pets~1{petId}/get'
          parameters:
            petId: '$response.body#/0/id'
          description: >
            The `id` value returned in the response can be used as
            the `petId` parameter in `GET /pets/{petId}`.

[xorcus]

Currently, the spec defines links property only in Response Object (links in Components Object do not help with this issue).

Would it be possible to add links property to Schema Object as well?
The $response.body#<non-negative-integer><JSON pointer> in this context would be resolved relative to each schema object instance in the response, yielding a link.

This way, getUserDetails operation simply returns an array of User schema objects which define the links derived from each instance. The client gets the array of links resolving the User schema object links relative to each instance received in the response.

My understanding is that x-links can already be used with this semantics in Schema Object because it allows for Specification Extensions.

[darrelmiller]

JSON pointers in this context would be resolved relative to each schema object

The JSON Pointer spec says,

Evaluation of a JSON Pointer begins with a reference to the root value of a JSON document

https://tools.ietf.org/html/rfc6901#section-4

We would have to redefine JSON pointers and the way fragment identifiers work to make this happen. I would recommend using JSON Hyperschema if you need to do this.... or actually do hypermedia.