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:
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,
