Openapi-specification: Path templating, multiple segments, and RFC 6570?

Created on 3 Mar 2015 · 39Comments · Source: OAI/OpenAPI-Specification

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?

OpenAPI.Next Proposal Sub Issue

Source

christav

👍28

All 39 comments

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.

webron on 3 Mar 2015

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

christav on 3 Mar 2015

:+1:

igr on 27 Apr 2015

👍🏻

dilipkrish on 25 May 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!

GitVhaos on 18 Jun 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.

webron on 18 Jun 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?

GitVhaos on 18 Jun 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.

webron on 18 Jun 2015

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

chrisdostert on 10 Oct 2015

+1 to include this in the next spec.

nikhiljindal on 4 Nov 2015

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

{/optionalSegment}
{+optionalReservedSuffix}

gwicke on 1 Dec 2015

I'm trying to implement :

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

maybe soon a PR :)

harobed on 1 Jan 2016

apissdks on 21 Jan 2016

Parent: #574

webron on 22 Feb 2016

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

drobri on 2 Mar 2016

:+1:

I need it at two different places:

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

Tronix117 on 7 Mar 2016

In an attempt to move this discussion forward in one direction or the other, here are questions that need to be addressed before we could move ahead with 6570 support.

6570 defines templates for the entire URI. Should the paths object still only include a template for the path portion of the URI, or 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? Do we need to support the + operator that allows parameters to not be escaped? Do we allow the * expansion operator and if so does that mean we need to introduce a new parameter type map? Optional path parameters? Prefix operator?
If a parameter appears in a template, must it also have a parameter object in the operation?
If a parameter is defined in the operation that is in the URL, must it appear in the template?

I'm sure there are more, but this gives us a place to start.

darrelmiller on 8 Apr 2016

@darrelmiller At the very least, it needs to support the * expansion operator. Without it there are an entire class of APIs (i.e. Dropbox) that cannot be represented. As per the original bug report.

christav on 8 Apr 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.

emattheis on 8 Apr 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.

darrelmiller on 8 Apr 2016

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

emattheis on 8 Apr 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 on 9 Apr 2016

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

dilipkrish on 9 Apr 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 :-\

darrelmiller on 9 Apr 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.

emattheis on 9 Apr 2016

👍1

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

mike-weadley on 17 Apr 2016

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

fiorix on 17 May 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.

gwicke on 17 May 2016