Support all HTTP Methods

[mightytyphoon]

Feature Request

OpenApi support for all http methods

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

• OPTIONS
• GET
• HEAD
• POST
• PUT
• DELETE
• 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
swagger-api/swagger-core#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?