Support all HTTP Methods

[mightytyphoon]

Feature Request

OpenApi support for all http methods

RFC 2616 updated by RFC 7231 (errata list for 7231)

• [X] OPTIONS
• [X] GET
• [X] HEAD
• [X] POST
• [X] PUT
• [X] DELETE
• [X] TRACE
• [ ] CONNECT

RFC 2518 updated by RFC 4918 and RFC 5689 for MKCOL

• [ ] PROPFIND
• [ ] PROPPATCH
• [ ] MKCOL
• [ ] COPY
• [ ] MOVE
• [ ] LOCK
• [ ] UNLOCK

RFC 3253 (errata list for 3253)

• [ ] VERSION-CONTROL
• [ ] REPORT
• [ ] CHECKOUT
• [ ] CHECKIN
• [ ] UNCHECKOUT
• [ ] MKWORKSPACE
• [ ] UPDATE
• [ ] LABEL
• [ ] MERGE
• [ ] BASELINE-CONTROL
• [ ] MKACTIVITY

RFC 3648

• [ ] ORDERPATCH

RFC 3744 (errata list for 3744)

• [ ] ACL

RFC 5323

• [ ] SEARCH

draft ietf httpbis safe method w body 03

• [ ] QUERY

draft snell link method 01

• [ ] LINK
• [ ] UNLINK

Related Issues

#658 #1306 #480 https://github.com/swagger-api/swagger-core/issues/1760

Iana link

Another link with methods and their RFC : iana

This post will be re-edited soon to add a small description for all methods

Regards.

[MikeRalphson]

HEAD has been supported since at least Swagger v1.2

[mightytyphoon]

@MikeRalphson updated, thanks.

[MikeRalphson]

Given the mission statement of the OAS as "standardizing on how REST APIs are described" could you expand on how some of these HTTP methods are being used within REST APIs (e.g. the WebDav methods are often seen as tied only to that protocol by their definitions)?

[mightytyphoon]

Given the mission statement of the OAS as "standardizing on how REST APIs are described" could you expand on how some of these HTTP methods are being used within REST APIs (e.g. the WebDav methods are often seen as tied only to that protocol by their definitions)?

Yes I think during next week I will edit this post to describe the methods, if they have a body, header, query, etc... how they should be used and some examples. I think it's what you want, if I understood your answer correctly ?

There is an inherent problem with REST because it wants to be very close to CRUD (Create, Read, Update, Delete) and even SCRUD (S for Search), but a REST API does so much more, like letting users subscribing and unsubscribing to a subject, users also want to connect to the API to have their data saved and secured, they will want to copy something, to move some datas, to lock their account, etc... that's what all these additional methods were made for.

For example to lock your account you could do a post to /accounts/lock with your token in header and in the post body add a parameter 'lock = true' but REST could handle it with just a LOCK request to /accounts and the token as a cookie header (or some encrypted data from localstorage as a token) which makes code clearer and really use the HTTP method verbose to add some logic in requests.

lock/unlock are described here as 'lock model'.

GET will have query params, with optional body, whereas HEAD will have no body and POST has an obligation to have a body, then responses can have a body or not depending on the method. So I have some research to do on this to give the right definitions, I will update very soon.

From wikipedia : http methods

Also there should be some methods to ignore, for example CONNECT which was made to create an ssl tunnel has, I think, no use anymore now with SSL/TLS certificates. But some could find a use for it, if they want to keep an http server and then control https connections opening.

CONNECT METHOD description on mozilla

EDIT : I also want to add that express supports these methods :

Express supports the following routing methods that correspond to HTTP methods: get, post, put, head, delete, options, trace, copy, lock, mkcol, move, purge, propfind, proppatch, unlock, report, mkactivity, checkout, merge, m-search, notify, subscribe, unsubscribe, patch, search, and connect.

source

[MikeRalphson]

lock/unlock are described here as 'lock model'.

But my point is that LOCK and UNLOCK as defined there are for use within the WebDAV protocol. They have no defined meaning (on their own) outside that protocol. They may be tied to specific XML request / response formats (forgive me, it has been a long time since I read the WebDAV RFCs).

A picture may be worth a thousand words:

[darrelmiller]

I'd be open to considering allowing HTTP method be an unconstrained string. I wouldn't want to re-enumerate all the methods in the IANA registry in the OpenAPI spec. We should consider what benefit tooling derives from it being an enumerated type.

p.s. Wow, that Wikipedia table is misleading. Describing a GET body as optional is just terrible.

[handrews]

Describing a GET body as optional is just terrible.

Far too many people don't seem to understand that "has no defined semantics" is standards-ese for "FFS don't do this!" and not "sure, do whatever!"

[cmheazel]

What is the expected behavior if my Path Item Object has an x-lock field associated with an Operation Object? Would that add Lock to the set of supported HTTP operations? If not, what else do we need to introduce these operations as Draft Features?

[MikeRalphson]

Extensions such as x-lock only have the meaning you give them and agree with third parties. Nothing more. Methods LOCK and UNLOCK only have defined meanings within the WebDAV protocol nowhere else. Outside of WebDAV their meaning also has to be mutually agreed by all parties.

[cmheazel]

@MikeRalphson Agreed. That is the nature of extensions. But if we can add HTTP operations using the extension mechanism, then we can use the Draft Feature process to measure demand. Draft Feature operations which are not implemented could be safely abandoned. Start with four or five of the least controversial ones.

[MikeRalphson]

I'm not against that in principle, like @darrelmiller says, maybe open it up with an extension which allows any HTTP method?

[egriff38]

Hello there, does anyone know if any effort has been made to create an extension which broadens the HTTP methods that can be described in Open API 3? Would like to take advantage of the SEARCH verb in my API but it looks like I am limited in my documentation at this time.

[ioggstream]

Given the ongoing work on HTTP & HTTPAPI I really suggest that we should:

• delegate methods support to HTTP
• add interoperability considerations suggesting to limit to the methods referenced in 7231 or I-D httpbis-latest
• include the fact that tooling might not supporting methods outside 7231

cc: @MikeRalphson @darrelmiller

[philsturgeon]

I'd support changing it to "any method defined in RFC 7231 and RFC 5323" but I'm not sure what value adding all those other ones provides?

I think its a little telling that SEARCH was what necro bumped this otherwise inactive topic. Probably just SEARCH is fine.

[ioggstream]

@philsturgeon I just won't ossify OAS with method decisions which are outside the OAS scope. If we want to provide stuff for implementers, we can say:

• implementers MUST support methds defined in 7231;
• implementers MAY support the other methods reported in the IANA table (see httpbis-semantics).

imho stuffing HTTP elements into OAS could provide more harm than benefits because iwe have no guarantee that the interpretation of HTTP we put into OAS is consistent with the latest specs (eg. see https://github.com/httpwg/http-core/pull/653/files).

My 2¢, and thanks for you time!

[philsturgeon]

@ioggstream I don't understand any individual parts of that reply let alone all of it together. I was saying "+ SEARCH" would be a good enough change to satisfy this issue because its the only one people seem all that fussed about.

[ioggstream]

@philsturgeon my opinion is that OAS should not constraint the possible set of http methods. This is because the HTTP specs are the place where methods are defined.

For interoperability reason, OAS could state that tooling implementers MUST support at least the methods defined in RFC7231.

Stating that methods outside RFC7231 are not supported at all is a imho weak design choice.

[karenetheridge]

I found this issue because I am writing a document that describes a "PURGE" endpoint, which is a non-standard HTTP method but none-the-less is very much in use in my application. Supporting any method matching the pattern "^[a-z]+$" would be very simple and straightforward; much more so than attempting to define a mechanism by which additional HTTP methods could be defined.

[bdunavant]

I found this issue because I'm writing docs to describe a MERGE endpoint (which is OData 1.0 and OData 2.0, but not HTTP spec), and really should have been written as PATCH but someone made an unfortunate decision years ago and that ship has sailed. While I understand OpenAPI's mission is documenting true REST, adding this flexibility will help a lot in places where someone made poor choices and/or didn't understand REST very well, and the rest of us have to live with it.

[eli-darkly]

My preference would be to have it allow any string, for the same reason @darrelmiller mentioned above. Really the decision of whether any given method is or isn't valid is the business of the service endpoint implementation; I don't see any value gained by having a general-purpose API tool make its own judgments on that.

However, if it is necessary to pick specific methods, I'll add one thing specifically about the REPORT verb. While it unfortunately is sometimes not allowed by HTTP clients, REPORT fills a specific need in HTTP APIs by being the method that 1. has a request body, 2. is idempotent, 3. is cacheable. GET can't (or shouldn't) have a body; POST isn't idempotent. Basically REPORT is what you would use if you want GET-like semantics but can't fit all the parameters into the URL.

[wparad]

I feel like step 1 is get published an RFC that has REPORT, QUERY, or SEARCH, then step 2 is add it. We don't need to support it be completely agnostic, while it's a great idea, and why would this tool restrict what is allowed...fundamentally there are tools that use this to implement and automate the spec. It doesn't do any good to enable bad patterns. We should enable good patterns, okay patterns, and necessary patterns. I need SEARCH and I love REPORT exists for webdav, but it doesn't exist for REST, and even if it did, non of the clouds support these verbs, so it wouldn't even have a real usage.

Help me get REPORT published to the right working group, and then it will defacto have to be added here. If we need another one, let's go through a similar process.

[eli-darkly]

@wparad:

fundamentally there are tools that use this to implement and automate the spec. It doesn't do any good to enable bad patterns

I don't understand what's meant by "bad patterns" here. Documenting the actual behavior of a web service is not a bad pattern, even if you feel that the web service should have used a more standard HTTP method. The person writing up an OpenAPI spec may not be the person who implemented the service, and may not have any control over its behavior, so punishing them by making it impossible for them to write such a spec is not helpful.

it doesn't exist for REST

There isn't a canonical REST specification that says what methods exist or do not exist. There are only conventions.

and even if it did, none of the clouds support these verbs, so it wouldn't even have a real usage

I don't understand this statement either. Whatever set of commonly used web hosts you're referring to as "the clouds", those are not the only hosts that could be running services that have an OpenAPI spec. OpenAPI can be used for literally any HTTP application.

[SVilgelm]

Please add the QUERY method: https://datatracker.ietf.org/doc/draft-ietf-httpbis-safe-method-w-body/

[ScotMeyer]

Please add the RAIN method. All joking aside, in section 16.1 of https://datatracker.ietf.org/doc/rfc9110/ the framers intended to allow for extensibility of Methods. If they didn't, I doubt they would have the registry https://www.iana.org/assignments/http-methods/http-methods.xhtml. I have yet to find in the REST Document, https://roy.gbiv.com/pubs/dissertation/top.htm, that suggests the methods described in RF7231 and RFC5789 are only for REST.

Example: I want the target resource, Oregon, to RAIN. I would issue: RAIN /Oregon

This would cause the resource Oregon to change its current State to RAIN on the server.

What about changing the state of the target resource, Chicago, to WINDY, I would issue: WINDY /Chicago

It shouldn't matter to the OpenAPI specification what choices the server/implementer makes to support. I believe that is the flexibility of OpenAPI. The alternative is using an existing verb to do this which IMHO seems like an anti-pattern.

In anti-pattern case, the above examples might be: POST /Oregon/actions/RAIN POST /Chicago/actions/WINDY

[karenetheridge]

Where are we at with this? As I (and many others) suggested above, we could remove the individual property declarations for get, post etc in the schema and replace them with:

patternProperties:
  ^[a-z]+$:
    $ref: '#/$defs/operation'

This would be a fast and easy win for 3.1.1 or 3.2.0.

[philsturgeon]

@darrelmiller maybe pop this one on the agenda for the next meeting? I'll come pester you folks on the call to chat about it. Seems like an easy win to just let operations be anything.

Tooling can stick to working with what it knows and warning against invalid.

Documentation can show what it knows and ignore what it doesn't, or just generically show everything.

Linters can validate against whatever current RFC they like and complain if you're using NONSENSE or whatever.

[wparad]

I feel like there has to be something more than just "everything could be a path". Without some sort of identifier, it impossible no tell the difference between:

• A method
• A not yet supported property

In reality we should just have all the methods under a property called "methods" just like all the paths are under "paths". Please don't allow both patterned properties that are * and also defined properties. Everyone is going to have a bad time.

It would be much better to introduce a new level called "methods" with the pattern properties of any word character of any length. And then tools could merge the two lists together. Easy. Take the known list at the top and merge it with the dynamic methods list.

Then we just mark the top level methods as deprecated in favor of the methods as a sub property of "methods"

For reference: https://spec.openapis.org/oas/latest.html#fixed-fields-6

[ScotMeyer]

@wparad so it would be MethodObject with a defined set of Methods (which the OperationObject https://spec.openapis.org/oas/latest.html#path-item-object contains now ie. get, post, put, patch, etc.) along with a user defined dynamic list of additional Methods.

So glad to see this moving forward! Postman has had this since 2018 https://blog.postman.com/custom-http-methods-more-flexibility-and-autonomy/

[darrelmiller]

@ScotMeyer

An anti-pattern case, the above examples might be: POST /Oregon/actions/RAIN POST /Chicago/actions/WINDY

My reading of the REST Uniform Interface constraint is that inventing new service specific methods would actually be the antipattern.

The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on > a uniform interface between components ([Figure 5-6] (https://roy.gbiv.com/pubs/dissertation/rest_arch_style.htm#fig_5_6)). By applying the software engineering principle of generality to the component interface, the overall system architecture is simplified and the visibility of interactions is improved. Implementations are decoupled from the services they provide, which encourages independent evolvability.

I do agree that the existence of the HTTP method registry indicates that adding new generic methods should not require a specification update and therefore constraining OpenAPI to a limited set of methods is probably not ideal.

[darrelmiller]

Thanks to @philsturgeon for raising this up to discuss in the TDC meeting https://github.com/OAI/OpenAPI-Specification/issues/3295

We did consider all the proposals discussed in this thread. In general there appeared to be consensus that supporting just the current set of methods is unnecessarily limiting. The current design of pathitem using fixed fields to identify methods is problematic in that new HTTP methods might conflict with current or future properties of pathitem. It is worth noting that the future moonwalk proposal doesn't suffer from this same design constraint.

Here are the options we discussed:

1. Add some additional subset of the methods defined in the HTTP registry as fixed fields to the pathitem object.
2. Add a property such as otherMethods to path item to enable adding additional methods to a description.
3. Recommend the use of an extension such as x-method-{method} to describe other HTTP methods.

The challenge with (1) is how do we pick the methods we want to include? Including all of the methods in the HTTP registry seems like overkill and won't help us as soon as new methods like QUERY are added.

Adding an official otherMethods solves the problem of naming conflicts but it doesn't really help driving support in tooling. Tooling vendors need to implement explicit support for merging these collections. Considering this solution is not something that would move forward into moonwalk we are concerned that we will see very little tooling support for it.

Encouraging the community to leverage extensions as a solution to "extending" OpenAPI seems like the right tool for the job. By following a pattern that uses the x-method- prefix we give an opportunity for tooling to add support for this extension and we can measure the interest in this capability based on presence of the extension with OpenAPIs documents and support in tooling. This will help guide us when it comes to moonwalk and whether we allow the method property to be any string or a known subset of strings.