Repository navigation
Flexible Path/URI Structure Using Linking #783
Description
Provide capabilities to replace the entire path structure via a response link mechanism (see #742). The path structure being returned may be a multi-segment path. There would be two options for replacing the path. They would be:
- Replace the path only without any change in the host or base path.
- Replace the path while overriding the host and base path.
In each case, the URI being returned from the response link is a concrete path (i.e., traversable) which may or may not include a scheme and host. It is not a template.
This allows for use cases where the link returned from a response may include a full URI (scheme, host, and path). We have key API specifications where this will be the case.
An example for how Option 1 and Option 2 may work is included below. Option 1 simply replaces the path without any changes to the host or base path already defined in the specification. Option 2 could be defined using "override host" and "override basepath" conditions as part of the parameter definition. In the example below for Option 2, it would be expected that the {version} variable would contain the scheme, host, basepath, and path:
Option 1
paths:
/{version}:
get:
operation id: componentVersion
parameters:
- name: version
type: string
in: path
required: true
responses:
200:
description: Component Version
schema:
$ref: '#/components/definitions/componentVersion'
/metadata:
post:
operationId: metadata
parameters:
- name: name
type: string
in: query
required: true
- name: value
type: string
in: query
required: true
responses:
200:
description: component metadata
schema:
$ref: '#/components/definitions/metadata'
links:
version:
#returns the version of a component
operationID: componentVersion
parameters:
- version: $response.header.links.version
Option 2
paths:
/{version}:
get:
operation id: componentVersion
parameters:
- name: version
type: string
in: path
override host: true
override basepath: true
required: true
responses:
200:
description: Component Version
schema:
$ref: '#/components/definitions/componentVersion'
/metadata:
post:
operationId: metadata
parameters:
- name: name
type: string
in: query
required: true
- name: value
type: string
in: query
required: true
responses:
200:
description: component metadata
schema:
$ref: '#/components/definitions/metadata'
links:
version:
#returns the version of a component
operationID: componentVersion
parameters:
- version: $response.header.links.version
Activity
darrelmiller commentedon Sep 10, 2016
Option 1 would be possible if we support the
separatorwith value/if the parameter is an array value, or if we support theescapedproperty, both are described in #778 .Option 2, might be enabled by whatever solution we come up with for #779. I'm not sure we necessarily need an explicit
override hostandoverride basepathproperty if the link provides parameters that are defined ashostparameters.lcrabb commentedon Sep 12, 2016
I really like #778 and #779 and believe they help with a number of challenges; however, there are specific challenges we are encountering which they do not address. Specifically, I am speaking of an implementation which does not specify the host as a separate parameter nor do the URIs adhere to any defined template.
In this implementation, they follow RCF 5988 and couple on a link relation. The relations are described in the HTTP header. Host is not specified separately and clients are explicitly discouraged from using a templated approach to craft their own URIs. There is no guarantee with that a given URI will always follow that format - it cannot be supported by the architecture.
With this in mind, I'm hoping options 1 and 2 are viable and could be used to support an implementation as I've described. I know others are much deeper into the specification than I am so if there are flaws in what I've proposed, I'm not opposed to some adjustments.
ePaul commentedon Sep 13, 2016
You might be interested in my proposal #577, which defines an "interface" (an operation without a path), which then can be bound to a URL in a link.
lcrabb commentedon Sep 13, 2016
@ePaul In concept what is described in #577 is what I would l like to see within the constructs of the linking mechanism described in #742. In the proposal I described, the "Operation ID" is similar to a link relation and the point at which clients will couple in our implementation (not on the path).
updated to support alternate link URLs, for #783
updated to support alternate link URLs, for OAI#783
handrews commentedon May 24, 2024
This scale of change is best discussed in Moonwalk (and can be backported if relevant and we decide to keep the 3.x line going). Closing in favor of:
updated to support alternate link URLs, for OAI#783