cancel
Showing results for 
Search instead for 
Did you mean: 

OAS Link object -- Why are parameters limited to JSON Pointer ?

Highlighted
New Contributor

OAS Link object -- Why are parameters limited to JSON Pointer ?

Hello,

 

Just wonder why are parameters in OAS Link object restricted to JSON Pointer ?

In the documentation of OAS runtime expression, there is even a note on this restiction:

 

JSON Pointer (the #/… part) uses 0-based indexes to access array elements. There is no wildcard syntax though, so $response.body#/users/*/id is not valid.

 

It would be super usefull to be able to express 1:n relation in OAS definition !

 

2 REPLIES 2
Highlighted
Moderator

Re: OAS Link object -- Why are parameters limited to JSON Pointer ?

Hi @sbenning,

 

There's an open discussion in the OpenAPI Specification repository about link syntax and possible improvements, please see if it answers your questions:

Variables/Parameters in Links


Helen Kosova
SmartBear Technical Writer
________________________

 Join SmartBear Connect next April in Boston to meet with software development, API and testing experts from around the world! Get your ticket today!
Highlighted
New Contributor

Re: OAS Link object -- Why are parameters limited to JSON Pointer ?

Hi @HKosova ,

 

Thank you so much for your quick response.

 

As I was hopping around, I indeed read about Variables/Parameters in Links -- Anymay, thank you for pointing this reference out. I didn't thought that it whas the good place for this question though.

 

In my opinion, this point is limiting OAS, as I cannot figure out, how to express `1:n` relationships betweens my operation responses and operation inputs.

 

I see OAS as a wonderfull specification to express the concepts behind a particular Rest API, for both human and machine.

 

I think OAS Link object is a great improvement for machine to be able to know, from an operation runtime response, the rules for autonomously constructing hypermedias for all related entities in that particular response. -- Only from spec time defined ruleset and a particular response instance -- So usefull !

 

But the usage of JSON Pointer to express those rules, is limiting the machine to only know about `1:1` relationships... So, my point is that I might misunderstand the concept / use case behind OAS Link object.

 

But from this doc point of view (at: https://swagger.io/docs/specification/links/)

 


Links are one of the new features of OpenAPI 3.0. Using links, you can describe how various values returned by one operation can be used as input for other operations. This way, links provide a known relationship and traversal mechanism between the operations. The concept of links is somewhat similar to hypermedia, but OpenAPI links do not require the link information present in the actual responses.

I still wonder why:

- If OAS Links are their for machine to be able to construct hypermedias, why are we limiting the runtime expression parser to JSON Pointer ABNF / syntax ? And so, we cannot gather array of links from arrays in the response's body.

- If OAS Links have a different meaning, what is their use cases ?

 

Anyway, I love the work done at OAS, and I would love to see futur improvments done over OAS Link if this is indeed a limitation.

 

Best regards,