Skip to content
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.

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

Flexible Path/URI Structure Using Linking #783

Closed
lcrabb opened this issue Sep 9, 2016 · 5 comments
Closed

Flexible Path/URI Structure Using Linking #783

lcrabb opened this issue Sep 9, 2016 · 5 comments
Labels
links Moved to Moonwalk Issues that can be closed or migrated as being addressed in Moonwalk

Comments

@lcrabb
Copy link

lcrabb commented Sep 9, 2016

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
Copy link
Member

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
Copy link
Author

lcrabb commented 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
Copy link
Contributor

ePaul commented 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
Copy link
Author

lcrabb commented 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).

AndersDJohnson pushed a commit to AndersDJohnson/OpenAPI-Specification that referenced this issue Apr 8, 2019
@handrews handrews added the links label Jan 28, 2024
@handrews handrews added the Moved to Moonwalk Issues that can be closed or migrated as being addressed in Moonwalk label May 24, 2024
@handrews
Copy link
Member

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:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
links Moved to Moonwalk Issues that can be closed or migrated as being addressed in Moonwalk
Projects
None yet
Development

No branches or pull requests

4 participants