Support all HTTP Methods

[mightytyphoon]

Feature Request

OpenAPI support for all HTTP methods

RFC 2616 (1999) updated by RFC 7231 (2014) (errata list)

• OPTIONS – Describe communication options (RFC 2616:1999 / RFC 7231:2014) → OpenAPI since 3.0 (2017)
• GET – Retrieve a resource (1999 / 2014) → OpenAPI since 3.0 (2017)
• HEAD – Retrieve headers only (1999 / 2014) → OpenAPI since 3.0 (2017)
• POST – Create or process a resource (1999 / 2014) → OpenAPI since 3.0 (2017)
• PUT – Replace a resource (1999 / 2014) → OpenAPI since 3.0 (2017)
• DELETE – Remove a resource (1999 / 2014) → OpenAPI since 3.0 (2017)
• TRACE – Diagnostic loop-back test (1999 / 2014) → OpenAPI since 3.0 (2017)
• CONNECT – Establish a tunnel (1999 / 2014) → OpenAPI explicitly allowed since 3.1 (2021)

  ✅ Spec 3.1 – Operation Object. CONNECT now explicitly covered.

RFC 5789 (2010)

• PATCH – Apply partial modifications to a resource (2010) → OpenAPI since 3.0 (2017)

RFC 2518 (1999), updated by RFC 4918 (2007) and RFC 5689 (2009, MKCOL)

• PROPFIND – Retrieve properties (1999 / 2007)
• PROPPATCH – Modify properties (1999 / 2007)
• MKCOL – Create a collection (1999 / 2009)
• COPY – Copy a resource (1999 / 2007)
• MOVE – Move a resource (1999 / 2007)
• LOCK – Apply a lock (1999 / 2007)
• UNLOCK – Remove a lock (1999 / 2007)

RFC 3253 (2002) (errata list)

• VERSION-CONTROL – Put a resource under version control (2002)
• REPORT – Run a server-defined query (2002)
• CHECKOUT – Checkout a versioned resource (2002)
• CHECKIN – Checkin a checked-out resource (2002)
• UNCHECKOUT – Cancel a checkout (2002)
• MKWORKSPACE – Create a workspace (2002)
• UPDATE – Update a resource to a specific version (2002)
• LABEL – Apply a label to a version (2002)
• MERGE – Merge changes (2002)
• BASELINE-CONTROL – Manage baselines (2002)
• MKACTIVITY – Create an activity (2002)

RFC 3648 (2003)

• ORDERPATCH – Reorder collections (2003)

RFC 3744 (2004) (errata list)

• ACL – Access control management (2004)

RFC 5323 (2008)

• SEARCH – Execute a search query (2008)

draft-ietf-httpbis-safe-method-w-body-03 (2015)

• QUERY – Safe method with body (2015, Internet-Draft)

draft-snell-link-method-01 (2014)

• LINK – Establish a relationship (2014, Internet-Draft)
• UNLINK – Remove a relationship (2014, Internet-Draft)

---

Related Issues

• HTTP Method REPORT not supported #658
• Support for SEARCH http method #1306
• Proposal: Support for LINK and UNLINK HTTP methods #480
• swagger-core #1760

References

• IANA registry of HTTP methods
• OpenAPI 3.0 Specification (2017)
• OpenAPI 3.1 Specification (2021)

---

👉 Notes:

• All RFC 7231 methods (GET, POST, PUT, DELETE, etc.) and PATCH are supported since OpenAPI 3.0 (2017).
• CONNECT explicitly allowed since OpenAPI 3.1 (2021).
• Other methods (WebDAV, ACL, SEARCH, QUERY, LINK/UNLINK…) remain not officially covered by OpenAPI tooling.

[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!