Allow operationObject overloading with get-^ post-^ etc

[DavidBiesack]

Currently under a pathItemObject, one can only define a single operationObject for each HTTP method (get, put, post, delete) etc. .

This limits OAS' ability to express many APIs, particularly those which allow multiple semantically different POST or GET operations on the same resource, such as different sets of query parameters or produces/consumes media types and associated schema.

This is a request to explicitly allow for this. Several other OAI/OpenAPI-Specification issues touch on this (notably #146 and the many issues which referred to it since 2014), but an explicit proposal to resolve this and allow overloading so is not yet forthcoming (or if it is, I'm not sure where it is...)

The proposal is to allow pathItemObject with new patterned fields corresponding to each operation. That is in addition to

  get
  put
  post
  patch
  delete
  head
  options

we also allow patterned names

  get-^
  put-^
  post-^
  patch-^
  delete-^
  head-^
  options-^

This differs from my initial proposal in #146 which used period (.) as a separator instead of hyphen (-), i.e. post.optimize, post.merge.

@darrelmiller also noted he was considering this, using the hyphen (-) notation:

paths:
   /customers:
       get-by-email:
          parameters:
              email: ...
          responses: ...
       get-by-name:
          parameters:
              firstname: ...
              lastname: ...
          responses: ...

I feel segregation into individual operationObjects is the best solution because it is a natural extension of the current syntax (compared to turning a path item into an array) or complicating a operationObject with multiple sets of body/header/query parameters and/or response schema (which might require adding complicated discriminators/tags or other ways to link related response/parameters within one large all-encompasing operation object.)

[fehguy]

I don't know why we would do this.

[darrelmiller]

@fehguy To allow people to have different behaviour based on query parameters. Because query parameters are part of the resource identifier and therefore could have different behavior. And currently people are doing ugly workarounds to be able to describe this.

[fehguy]

But this is an even uglier work around. I consider the "path per http operation" to be part of our own, intentional limitations, not something to just find a work-around for.

[darrelmiller]

It's not uglier than putting fragments on the end of paths. Or using oneOf in the schema and creating a union of query parameters. And it is definitely not uglier than the x-ms-paths solution.

I have no problem if OpenAPI wants to enforce that "style" of HTTP API, but we need to recognize that we are preventing people with perfectly valid HTTP APIs from being able to use OpenAPI to describe their APIs.

[fehguy]

I'm just suggesting, that if we're going to open up the discussion again to overloading the http method + path discussion, this is probably not the way to do it.

Personally I think we would regret doing so, the tooling would be literally impossible to write and that would mean very little value to end users.

[darrelmiller]

My apologies for rehashing covered ground. I wasn't involved in previous discussions of this.

I am surprised that you feel it would make tooling impossible. I know this is how ASP.NET does routing, and I know that AutoRest uses the x-ms-path workaround to enable this. @dilipkrish has said he a workaround working in SpringFox.

The value it brings to users is dependent on whether they are trying to describe an API that happens to follow the rule of using only the path for resource identification or not. For those who didn't happen to follow that arbitrary rule, it kinda sucks because they don't get the benefits of the OpenAPI specification or Swagger tooling.

But, as you said, you've had this debate before and made a choice. I'm happy to respect that and move on.

[MikeRalphson]

@darrelmiller one potential work-around if the server ignores it is to use a dummy fragment (#whatever) at the end of the paths to distinguish them.

The spec. also seems to allow for a hard-coded ?param in the path, if it is a fixed value of the parameter (or presence of the parameter) which controls the different behaviour. I am not sure of the support in various tooling for these work-arounds.

[DavidBiesack]

Please @webron comments on #146 here, here and here, also @fehguy here. #182 is similar (also with lots of 1+'s)

There are many people asking for the ability to cleanly segregate semantically different operations for each path/method . The frameworks (JAX-RS, Spring, others as Darrell mentioned above) support it. The frameworks support it support it because it is how people think about and design their APIs and map them onto HTTP. The solution need not be this approach; I'd be happy to review other proposals... perhaps I've missed them.

Based on the previous comments on #146 / #182, I thought this was a high priority change slated for 3.0. Granted OpenAPI cannot address 100% of APIs, but I think the community clearly expects/demands this from OpenAPI Specification 3.0, and OAI members have agreed in the past that addressing this deficiency is important.

[darrelmiller]

@MikeRalphson The hope was to make these scenarios something you didn't have to "workaround". I don't like idea of telling people to put things in the path key that are not part of the URL path.

[fehguy]

Per @OAI/tdc call we will not consider this for the 3.0 spec, labeling it as such

[ePaul]

Just out of curiosity, are those calls open for participation? I didn't find any announcements about those calls anywhere (only occasionally reports of results from them), just https://openapis.org/governance stating that the TDC is open to any developer.

[omidgfx]

Hello!
Everyone hates the limitation in their API design!
It's a fact! I known it's more clear to having different routes for different HTTP operations.
But sometimes, our apps just getting too complex, and we can not redefine a new route for same purpose with a small difference.
Like: I have a Verification Request API, which supports two different types of verification, one is for sending OTP via SMS and the other is for sending OTP via email. there's no need to define a new route. So I've done it with a query parameter: verification_type=sms|email.

In my case, (Regardless of whether my API does two different operations), there is a case that maybe my rate-limiter blocks (prevents) the user to request too-many verification codes and then responds HTTP 423 with a message like "You've been blocked due to rate limitation", and also when user has been blocked (restricted by admin) then my same API responds another HTTP 423 with another message like "Your profile has been restricted".

I'm aware of the keyword oneOf, but It's not what I need, I need a complete new response with same response code and different description and different schema, so I can clearly display all about what is happening and what is my back-end's behavior in different situations.

[omidgfx]

Also look at this:
https://stackoverflow.com/q/62788183/836979
It makes sense but look how messy is the solution !

As a developer, I expect everything to be clear and be there, Without looking for it.

[handrews]

This sort of thing is being addressed in OAS 4 Moonwalk as part of the operation signatures principle. Please join the discussions in that repository if you are still interested!