Flexible Path/URI Structure Using Linking

[lcrabb]

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:

1. Replace the path only without any change in the host or base path.
2. 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

[darrelmiller]

Option 1 would be possible if we support the separator with value / if the parameter is an array value, or if we support the escaped property, 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 host and override basepath property if the link provides parameters that are defined as host parameters.

[lcrabb]

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]

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]

@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).