Links proposal (updated) #742
Conversation
|
To support operation linking, as suggested in #688, I propose the following:
Additional considerations:
Spec changes
|
| missingValue: null | ||
| ``` | ||
|
|
||
| In situations where variables appear in an array, an array of variables will be extracted. For example: |
There was a problem hiding this comment.
This needs more documentation
| operationId| string | the name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`. This field is mutually exclusive with the `href` field. Relative `href` values _may_ be used to locate an existing Operation Object in the OAS. | ||
| parameters | Link Parameters Object | an Object representing parameters to pass to an operation as specified with `operationId` or identified via `href`. | ||
| description | string | a description of the link, supports GFM. | ||
| ^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details. |
There was a problem hiding this comment.
@ralfhandl I added description and x-* extensions
| href | url | a relative or absolute URL to a linked resource. This field is mutually exclusive with the `operationId` field. | ||
| operationId | string | the name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`. This field is mutually exclusive with the `href` field. Relative `href` values _may_ be used to locate an existing Operation Object in the OAS. | ||
| parameters | Link Parameters Object | an Object representing parameters to pass to an operation as specified with `operationId` or identified via `href`. | ||
| headers | Link Headers Object | an Object representing headers to pass to the linked resource. |
There was a problem hiding this comment.
@DavidBiesack With the addition of headers for the linked resource, we can traverse media types now.
|
approved by @OAI/tdc |
|
I was approaching this PR with some hope that it could be used to support hypermedia types being represented in OAS, but I see now that there's a requirement for the links to be "static." This requirement alone breaks the coupling semantics for Web Linking, on which (nearly?) all the hypermedia types depend. And that's okay if that's not the supported use case for this feature. But it leaves me a bit bewildered. Can someone help by defining use cases or existing APIs that could benefit from this feature in its current form? It seems like this introduces a lot of hopping around between references to grok what's going on. What are the intended benefits? Maybe it's obvious to most people. Hopefully, it is. But right now, I'm in the dark. Thanks. |
|
@kevinswiber consider reading the comments in the previous (mangled) PR and the corresponding issues for the rationale |
The previous PR was updated, and the comments got all jacked up. So here's a new PR, the old one has been closed but you can see comments there in all their glory.