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

Path templating, multiple segments, and RFC 6570? #291

Closed
christav opened this Issue Mar 2, 2015 · 39 comments

Comments

Projects
None yet
@christav

christav commented Mar 2, 2015

I'm trying to write swagger docs for APIs like dropbox where the number of path segments isn't known ahead of time. For example, the path template will look something like:

/api/metadata/{filePath}

And the following urls should all match this path:

/api/metadata/file1.txt
/api/metadata/dir1/file2.txt
/api/metadata/dir1/dir2/file3.txt

If we were using RFC 6570, I'd represent this as:

/api/metadata/{/filePath*}

but the swagger v2 spec doesn't say if this syntax is acceptable or not.

If it is acceptable/correct, could you please let me know in this item? If it's not, what is the expected way to model APIs like this with runtime variable URI paths?

@webron

This comment has been minimized.

Member

webron commented Mar 2, 2015

Currently, Swagger 2.0 doesn't support it. It's been discussed in the workgroup but we have decided to exclude it. I imagine it has a very good chance of being included in the next version of the spec though.

@christav

This comment has been minimized.

christav commented Mar 3, 2015

Thanks, please then consider this a vote for some solution to this problem in the next rev of the spec.

@igr

This comment has been minimized.

igr commented Apr 27, 2015

👍

1 similar comment
@dilipkrish

This comment has been minimized.

Contributor

dilipkrish commented May 25, 2015

👍🏻

@GitVhaos

This comment has been minimized.

GitVhaos commented Jun 18, 2015

Does this bug imply that it is not possible to have multiple REST-API "Search" operations for same resource?
"/rest/resource?param1"
"/rest/resource?param2&param3"
...
This would be a big problem for us to use swagger!

@webron

This comment has been minimized.

Member

webron commented Jun 18, 2015

It's not a bug, it's a feature request (can't believe I just said that).

If your query parameters are mutually exclusive, you can't define that, but that's not related to this feature but another one here. If you're just looking to describe multiple parameters, there's no problem with that.

@GitVhaos

This comment has been minimized.

GitVhaos commented Jun 18, 2015

Okay let`s name it feature ^^
I´m exactly referencing to the springfox-swagger "feature" dilipkrish linked above.
Can u please tell me the issue number of the "other feature" u wrote about, so I can track it?

@webron

This comment has been minimized.

Member

webron commented Jun 18, 2015

It actually relates to #164, not this one. We can't treat RFC 6570 as a single feature. Not saying it won't all be implemented, but we need to have separate issues for separate sections of it so we know we cover it properly.

@dilipkrish dilipkrish referenced this issue Aug 4, 2015

Closed

Support for RFC6570 #541

0 of 2 tasks complete
@chrisdostert

This comment has been minimized.

chrisdostert commented Oct 9, 2015

+1 and curious about how to track/participate in the workgroup on this issue?

@nikhiljindal

This comment has been minimized.

nikhiljindal commented Nov 4, 2015

+1 to include this in the next spec.

@gwicke

This comment has been minimized.

gwicke commented Dec 1, 2015

+1 for adding at least partial RFC 6570 support from me as well. We already use these local extensions:

  • {/optionalSegment}
  • {+optionalReservedSuffix}
@harobed

This comment has been minimized.

harobed commented Jan 1, 2016

I'm trying to implement :

  • {/path}
  • {path*}
  • and {/path*}

maybe soon a PR :)

@apissdks

This comment has been minimized.

apissdks commented Jan 21, 2016

+1

@webron

This comment has been minimized.

Member

webron commented Feb 22, 2016

Parent: #574

@drobri

This comment has been minimized.

drobri commented Mar 1, 2016

+1 for adding RFC 6570 support from me as well.

@Tronix117

This comment has been minimized.

Tronix117 commented Mar 7, 2016

👍

I need it at two different places:

  • FS-like path: /fs/dir1/dir2
  • Access to a sub API, referenced somewhere else: /subapi/resource/id/...
@emattheis

This comment has been minimized.

emattheis commented Apr 8, 2016

I propose merging the functionality of the current path and query parameter types under a new type called uri which would allow the parameter to apply to the URI template according to 6570.

@christav I think the reserved character (+) operator is what you're looking for. I, too, require this for an API I manage that presents an arbitrary hierarchy.

I also need support for the explode (*) modifier to support passing arbitrary name/value pairs in query params.

@darrelmiller

This comment has been minimized.

Member

darrelmiller commented Apr 8, 2016

@emattheis Either + or * could be used. + would work if the parameter was a string with a set of segments predefined. * would work if you passed an array of segment values.

As the path is currently used as the key for operations, it is not as simple as creating a new property with a new name. It would require changing the specification of the key value that appears in the paths object. I have no objection to heading in that direction, but I suspect other people might. That's what I'm hoping we can surface here.

@emattheis

This comment has been minimized.

emattheis commented Apr 8, 2016

@darrelmiller Ah, that's right. I was thinking of my particular case where I want the entire sub-path as a string...

@dilipkrish

This comment has been minimized.

Contributor

dilipkrish commented Apr 9, 2016

do we consider adding the query string to allow different operations based on query string parameters?

👍

What features of 6570 templates should we not support?

IMO the spec shouldn't limit this to tool chain capabilities. While certain tool chains might be able to support it with higher fidelity, we should atleast support the subset that can be described by parameter definitions.

If a parameter appears in a template, must it also have a parameter object in the operation?

My vote is yes, because the parameter definitions can have type information that cannot be described by the path alone.

If a parameter is defined in the operation that is in the URL, must it appear in the template?

For consistency I'd say yes

@dilipkrish

This comment has been minimized.

Contributor

dilipkrish commented Apr 9, 2016

Also there is a working reference implementation using the java + spring + trickedout-swagger-ui stack.

@darrelmiller

This comment has been minimized.

Member

darrelmiller commented Apr 9, 2016

Option 1
We add support for operators + . / ; in path segments. We allow both prefix and expansion modifiers but only support array parameters. This means the only part of the spec that would require updating is the Path Templating section. A standard 6570 parsing library could be used by tooling libraries.
This would allow for optional path segments and a dynamic number of path segments by using arrays and the expansion modifier. It would also allow for unescaped parameters.

The risk of allowing unescaped parameters is that it would make tools like swagger inflector difficult to implement as it becomes challenging to match URIs to templates when parameters can contain URL delimiter characters. The common scenario for unescaped parameters is when the host is being parameterized but considering the paths property doesn't include the host, I'm not sure what other use cases exist.

Option 2
We do everything in Option 1 but also add a new parameter type called map. This would allow matrix parameters like this,

 //moremaps.com/us/ma/cambridge;scale=50000;roads=main

Standard 6570 parsing libraries can still be used.

Option 3
We support templates for both path and query parameters. We would provide full RFC 6570 support and the map parameter type would need to be added.

Previously it was decided that including query string parameters in the path key would introduce significant amount of additional complexity when it comes determining path identity. Some cited concerns involve optional parameters, literal values, and parameter ordering.

e.g.

  /foo{?bar,baz}
  /foo{?baz,bar}
  /foo?bar=1{&baz}  

Are these considered three, two or one distinct paths? From a specification and documentation perspective, a spec author could explicitly choose which of these need to be described separately. However for tools like Inflector and Codegen it could cause some challenging situations.
The optional parameter is not actually new complexity because Option 1 would introduce that with path parameters.

Despite the additional complexity, there appears to be fairly significant support #164 for adding this capability.

One final issue, if this option is adopted, can we really continue to call the parent property "paths"? Or do we need to have to call it PathAndQueries :-\

@emattheis

This comment has been minimized.

emattheis commented Apr 9, 2016

Option 3 gets my vote.

I would argue that merging query params into the path template may make the overall specification simpler in light of #574 - the uniqueness of an operation could remain verb + path and satisfy the demands for including more variability if the path template had full RFC 6570 support.

Just to add a real-world use case for unescaped parameters: I maintain an API that represents a virtual filesystem with an endpoint /resources{+path} where the path variable represents the path of the resource (folder or file) in the virtual filesystem - e.g. /path/to/some/folder/ or /path/to/some/file.

@mikeweadley

This comment has been minimized.

mikeweadley commented Apr 16, 2016

+1 for at least Option 2. I have APIs that make heavy use of matrix parameters. For each endpoint, some matrix parameters are required and others optional. I like the notion of documenting both (required and optional) in the parameters object.

@fiorix

This comment has been minimized.

fiorix commented May 17, 2016

+1
I just hit the problem of not being able to express /path/*, which is surprising.

@gwicke

This comment has been minimized.

gwicke commented May 17, 2016

Option 1 (optional paths) seems to address most immediate needs, and avoids figuring out all the complexity of option 3.

Option 3 (query strings) could be added on top of Option 1 later. This would provide some extra time to figure out the desired semantics re uniqueness. To me, ignoring the query string part of the URL spec for uniqueness seems to be the most consistent way to go about this, but there are several other options on the table.

I do not care as much about the map functionality in Option 2. If this is added, then I would prefer to do this in line with RFC 6570.

@fpoolev

This comment has been minimized.

fpoolev commented Jul 28, 2016

+1

@git03394538

This comment has been minimized.

git03394538 commented Aug 23, 2016

+1

2 similar comments
@MaksimOrlov

This comment has been minimized.

MaksimOrlov commented Sep 18, 2016

+1

@hhashoww

This comment has been minimized.

hhashoww commented Dec 9, 2016

+1

@GlenDC

This comment has been minimized.

GlenDC commented Jan 11, 2017

+1

@pbarker

This comment has been minimized.

pbarker commented Feb 10, 2017

+1

@fehguy

This comment has been minimized.

Contributor

fehguy commented Feb 10, 2017

You can see what has been added by looking at changes in this PR:

#804

@pg26

This comment has been minimized.

pg26 commented Jul 1, 2017

+1
I am using swagger 2.6.1 and am not being able to express /path/*. Does 3.o support this?

@sodiumjoe

This comment has been minimized.

sodiumjoe commented Jul 20, 2017

@EtienneK

This comment has been minimized.

EtienneK commented Aug 30, 2017

+1

1 similar comment
@janos-roche

This comment has been minimized.

janos-roche commented Sep 7, 2017

+1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment