Support optional path parameters with default value

[amarzavery]

As of today, Open API spec asserts that a path parameter should always be required. This is a good assertion.
However, we have some services in Azure that have optional path parameters with a default value. There has been an increasing number of requests from service teams to support this.

What do you think about the following assertion?

If the parameter is in "path", required field must be specified. If required is false, it must be supported with a default. Else, required filed should be true.

This provides more flexibility apart from taking care of the current assertion.

For example:

• "/kevault/{KeyType}"

{
  "name": "KeyType", 
  "in": "path", 
  "required": false,
  "default": "symmetric",
  "type": "string", 
  "description": "The type of key."           
}

Can this be included in the 3.0 version of the Open API Spec?

[webron]

Given the planned support for some other aspects of RFC6570, the requirement that path parameters are mandatory may drop altogether.

[amarzavery]

That would really awesome :)

[amarzavery]

Do you have a time range for when will the next version be public?

[webron]

Within a few months. The process itself is public so people can voice their opinions as we progress.

[fehguy]

Parent issue #574

[darrelmiller]

@amarzavery As noted on the original Autorest issue, 6570 optional path parameters wouldn't quite meet the needs of the original example.

[swettstein]

Given the planned support for some other aspects of RFC6570, the requirement that path parameters are mandatory may drop altogether.

and yet 3 1/2 years later, they still appear to be mandatory

[fehguy]

I think @webron used the word "may" because it's not for sure changing...

[swettstein]

i have seen lots of discussions about path parameters containing slashes but nothing on this issue regarding simple path parameters.

from what i've read so far, OAS is designed to be how one SHOULD describe an API, not meant to support how APIs have actually been implemented. if that is indeed accurate, then why SHOULD path parameters be mandatory?

[fehguy]

Quite simply, making path parameters optional changes the path semantics and can make resolution of the operation non-deterministic. I know we can all think of one-off use cases where one can justify why it makes sense that POST: /foo/{bar}/{baz}/{bat} may not overlap with POST: /foo/123 (bat was optional) but in the general case, it makes routing difficult to impossible.

[SheepReaper]

@fehguy I disagree with your non-determinism comment. I argue that path resolution is non-deterministic by default. For example:

blog.domain/api/post/latest

Is deterministic because it always processes the same logic to reliably retrieve the latest blog post. It's also non-deterministic because there's no guarantee that between calls the same blog post will be retrieved.

blog.domain/api/post/1
blog.domain/api/post/2
blog.domain/api/post/3

Are deterministic because they always return the exact same post respectively. However, you're nuts if you think I'm going to specify a path for every post that exists (extreme example) <- and revise my spec every time a new blog post is created.

OAS is a specification for describing an API. It is not an example or reference for how an API should be implemented nor does it have anything to do with how path resolution is implemented.

I implement my API and I wish to document it. I wish to document it in a standard way to that doc generation tools can deterministically (reliably) generate the docs accurately. I have optional path (route) parameters. I cannot trust that any doc generator will correctly generate a doc for my API because if the generator is OAS-compliant, it MAY ignore or throw an error when it encounters required: false in a parameter definition that also includes in: 'path'.

This is an unreasonable restriction.

EDIT: (forgot to finish my thought)
In all cases, blog.domain/api/post/ irrespective of what follows reaches the same resource on my server which then decides how to handle what comes after the '/' <- but that's my implementation choice, and I currently have no way of documenting that. I may, for example, wish that for the case of no argument, return the latest by default or a collection of posts.

[KenEucker]

Jumping in here late to say that I also wish for this to be implemented. My use case is the same as @bryan5989 above, in that I have paths:

blog.domain/api/post/1
blog.domain/api/post/2
blog.domain/api/post/3

and I also have

blog.domain/api/post/latest

My server receives requests at the root blog.domain/api/post/ synonymous with the requests above by provided POST values. My path looks like this:

     * /api/post/{post_id}:
     *   post:
     *     parameters:
     *       - in: formData
     *         name: post_id
     *       - in: path
     *         name: post_id

So a POST request to blog.domain/api/post/ with the body { post_id: "latest" } receives the same response as blog.domain/api/post/latest provides. And requests that come in at /api/post/ without the {post_id} parameter receive the same response as /api/post/latest (default: "latest").

This is how my application is structured and I would like for it to be documented properly. The reason I would like to be able to document this properly is so that my generated API requests are properly formatted. Right now, when using swagger-ui to connect using my given swagger.json, requests without filling in the optional path parameter look like this:

POST blog.domain/api/post/undefined

[SheepReaper]

@fehguy I disagree with your non-determinism comment. I argue that path resolution is non-deterministic by default. For example:

blog.domain/api/post/latest

Is deterministic because it always processes the same logic to reliably retrieve the latest blog post. It's also non-deterministic because there's no guarantee that between calls the same blog post will be retrieved.

blog.domain/api/post/1
blog.domain/api/post/2
blog.domain/api/post/3

Are deterministic because they always return the exact same post respectively. However, you're nuts if you think I'm going to specify a path for every post that exists (extreme example) <- and revise my spec every time a new blog post is created.

OAS is a specification for describing an API. It is not an example or reference for how an API should be implemented nor does it have anything to do with how path resolution is implemented.

I implement my API and I wish to document it. I wish to document it in a standard way to that doc generation tools can deterministically (reliably) generate the docs accurately. I have optional path (route) parameters. I cannot trust that any doc generator will correctly generate a doc for my API because if the generator is OAS-compliant, it MAY ignore or throw an error when it encounters required: false in a parameter definition that also includes in: 'path'.

This is an unreasonable restriction.

EDIT: (forgot to finish my thought) In all cases, blog.domain/api/post/ irrespective of what follows reaches the same resource on my server which then decides how to handle what comes after the '/' <- but that's my implementation choice, and I currently have no way of documenting that. I may, for example, wish that for the case of no argument, return the latest by default or a collection of posts.

2 years later, I've realized that I misused the term resource in my final thought above. That said, I restate my point that an OAS pathspec does not determine whether you'll get a resource or something else (not a resource) at that path. That's for I the implementer to decide. Which is the whole point of documenting an API in the first place and the reason why OAS should allow me to decide whether a path segment is optional or not. Generator implementors can add switches to honor/ignore that preference.

[rossginn]

My API follows a pattern in which resources can be addressed using its ID within the path. All other params are query params.
GET /api/widget/ - returns all widgets
GET /api/widget/{id} - returns a widget

It'd be nice if OpenAPI allowed this pattern, as nearly all REST frameworks do.

[rafalkrupinski]

@rossginn
What's wrong with having two path elements in your opeanpi?
Different parameters, different results... What's the point of having it under one path element?

[rossginn]

@rafalkrupinski
The implementation is single endpoint with an optional path param, which is valid REST wise, so it seems it should be reflected that way in the documentation.

Also, consider query params that may exist, for example /api/widget?color=green. Using 2 path elements to get around the required rule results in these query params being documented on the GET /api/widget/{id} path, as it's a single implementation, which is problematic.

[rafalkrupinski]

@rossginn
That's a tooling problem. You can simply make two functions or methods and have one call the other.

[handrews]

Moonwalk (OAS 4) is currently slated to fully support RFC 6570. Please join the discussions in the Moonwalk repository to help work out the details for this sort of thing! As it will not fit in a 3.x release, I'm closing it out of this repository.