Skip to content

updated to support alternate link URLs #797

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

updated to support alternate link URLs #797

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion versions/3.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1173,7 +1173,8 @@ The `Link Object` is responsible for defining a possible operation based on a si

Field Name | Type | Description
---|:---:|---
href | url | a relative or absolute URL to a linked resource. This field is mutually exclusive with the `operationId` field.
href | url | a relative or absolute URL to a linked resource definition. This field is mutually exclusive with the `operationId` field.
url | url | a relative or absolute URL representing the target location for the link operation. This is used to override the `{scheme}://{host}/{basePath}` defined at the global level for the linked operation.
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.
Expand All @@ -1184,6 +1185,23 @@ Locating a linked resource may be performed by either a `href` or `operationId`.
In the case of an `operationId`, it must be unique and resolved in the scope of the OAS document.
Because of the potential for name clashes, consider the `href` syntax as the preferred method for specifications with external references.

When the `url` attribute is provided, the target host may be overridden by the value provided. For example:

```
components:
links:
UserRepositories:
operationId: getRepositoriesByOwner
url: $responseHeaders.link
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that should be $responseHeader.link? (At least the table with the variable substitutions has it in singular.)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, the examples in the table below have the variables in braces (i.e. {$responseHeader.link}, here they are raw. I think we should always use the braces, or at least define it clearly when they can be omitted.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, this is a minor doc change, we'll address that while starting a sweep of the docs next week

definitions:
user:
type: object
```

will extract the URL from the response header named `link`. If an absolute URL is provided, it will be used instead of the server / path provided in the target operation. Parameters _may_ be provided as well. If a `path` parameter is provided, it shall be ignored unless the `url` value contains a matching location for substitution. If query parameters are provided in the `url` value, they will be interpreted per the operation definition, and the absence of a required query parameter will result in an invalid request.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "absolute"/"relative" URL distinction happens after replacement of response payload variables, right?

Same for the path parameter values? (I.e. the response can include a URI template, which will then be filled using the parameters settings with parameter values provided by the client.)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The intent is that you have /foo/bar/{username}/baz as a relative URL, we will use the document's host, scheme, and the supplied url of /foo/bar/{username}/baz. If a parameter is extracted from the payload, it too would be used for the substitution


When a relative path is provided in the `url` attribute, the host defined in the specification will be used.

#### <a name="responsePayload"></a>Response Payload Values

Payload values are only available in parseable response payloads which match the advertised media-type.
Expand Down