Conceptually I agree that we should conform to the spec (even though I don't really understand the OpenAPI people's unwillingness to incorporate optional path parameters - they are called parameters after all). On the practical side, though, copy/pasta would arguably be harder to maintain properly and across multiple projects/repos. In addition to the proliferation of lines in YAML specs, there is also the visual issue of auto-generated docs: we would at least double the number of paths, and that could become unwieldy very quickly; if you consider the current REST API docs it is clear that this would not be sustainable.

To deal with the YAML spec problem, we could try using YAML references. But how do we deal with the docs issue?

I would say we should update our swagger to 3.0 and become standard-compatible.

In 3.0 there's a new concept of components that would deal with the issue of copy-pasta, and, although 30% more routes makes the docs harder to read, we can make the tags for routes more fine-grained.

We will need to go swagger 3 no matter what, the upstream support for swagger 2 is over, and as our fork diverges more and more from upstream the risk of getting a non trivially fixable security issue grows. As for standard-compatibility, I think 30% bit more items in the list would be a small price to pay for all the benefits @akosiaris described.

After reading the openapi spec and examples, I think the best approach to address optional params is by making them query paramters

So, an example path like this

/required{/optional1}{/optional2}

can be just

/required?optional1=value1&optional2=value2

As per spec query parameters can be optional. But this kind of change would mean that we need a new version of api so that we don't break old path based approaches. Plus a deprecation plan.

Well instead of copy/pasta, there is that thing called YAML anchors/references that deal with data repetition in YAML files.

Let's get ourselves spec-compliant :)

In T217881#5016597, @santhosh wrote:

After reading the openapi spec and examples, I think the best approach to address optional params is by making them query paramters

So, an example path like this

/required{/optional1}{/optional2}

can be just

/required?optional1=value1&optional2=value2

As per spec query parameters can be optional. But this kind of change would mean that we need a new version of api so that we don't break old path based approaches. Plus a deprecation plan.

I would advise against making a breaking change to our API so that a YAML file is easier to write.

I would advise against making a breaking change to our API so that a YAML file is easier to write.

My understanding here is, having our spec standard compliant is first priority. Currently our apis are not. A good standard is supposed to make the spec easily maintainable. The candidate standard here is https://swagger.io/specification - OpenAPI spec 3.x

In T217881#5016597, @santhosh wrote:

/required?optional1=value1&optional2=value2

Doesn't this introduce the problem of parameter ordering? In my mind, the only major advantage of path based parameters is the fact that the caching layer dosn't have to deal with an exponential number of equivalent URLs.

https://cxserver.wikimedia.org/v2?doc#!/Tools/get_v1_list_tool_from_to has two optional parameters from and to. However, from is not optional if to is provided. The UI allows to input only to, but it will in fact return results as if only from was specified.

This can either be seen as a limitation (if all parameters are optional and independent) or a feature in case there is a dependency on the following path parameters on the preceding ones (like, title must be provided if section is provided). The case for title and revision is less clear, since revision ids are unique across titles, so revision id alone could be sufficient.

Looking at the docs, most apis only have single optional parameter at the end (like revision). It's not clear to me why this has been made a path parameter as opposed to a "regular" parameter.

Well instead of copy/pasta, there is that thing called YAML anchors/references that deal with data repetition in YAML files.

That, plus some new features of swagger 3.0

It's not clear to me why this has been made a path parameter as opposed to a "regular" parameter.

In order to avoid issues with query parameter ordering and thus improve caching.

Let me clarify the current semantics between multiple optional parameters. Example:

The path like:

/{foo}{/bar}{/baz}

Unfolds into 3 possible paths:

/{foo}
/{foo}/{bar}
/{foo}/{bar}/{baz}

but NOT

/{foo}/{baz}

so in our fork of swagger, the optional parameters are hierarchical - you can only specify the next parameter if you did specify the previous.

Let's get ourselves spec-compliant :)

+1 from me. For individual services, it would be fairly easy to do, RESTBase though is another be beast, however going spec compliant and swagger 3 will allow us to simplify some code quite a bit.