Path templating, multiple segments, and RFC 6570?

[christav]

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]

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]

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

[igr]

👍

[dilipkrish]

👍🏻

[GitVhaos]

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]

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]

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]

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.

[chrisdostert]

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

[nikhiljindal]

+1 to include this in the next spec.

[gwicke]

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

• {/optionalSegment}
• {+optionalReservedSuffix}

[harobed]

I'm trying to implement :

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

maybe soon a PR :)

[rajeshkamal5050]

+1

[webron]

Parent: #574

[drobri]

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

[Tronix117]

👍

I need it at two different places:

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

[dilipkrish]

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]

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

[darrelmiller]

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]

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.

[mike-weadley]

+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]

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

[gwicke]

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]

+1

[git03394538]

+1

[MaksimOrlov]

+1

[hhashoww]

+1

[GlenDC]

+1

[pbarker]

+1

[fehguy]

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

#804

[pg26]

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

[sodiumjoe]

looks like it won't be supported in 3.0

[EtienneK]

+1

[janos-roche]

+1