Support all HTTP Methods #1747
Comments
|
|
|
@MikeRalphson updated, thanks. |
|
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 :
|
But my point is that A picture may be worth a thousand words:
|
|
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. |
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!" |
|
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? |
|
Extensions such as |
|
@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. |
|
I'm not against that in principle, like @darrelmiller says, maybe open it up with an extension which allows any HTTP method? |
|
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. |
|
Given the ongoing work on HTTP & HTTPAPI I really suggest that we should:
|
|
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. |
|
@philsturgeon I just won't ossify OAS with method decisions which are outside the OAS scope.
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! |
|
@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. |
|
@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. |
|
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 |
|
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. |
|
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 |
|
I feel like step 1 is get published an RFC that has Help me get |
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.
There isn't a canonical REST specification that says what methods exist or do not exist. There are only conventions.
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. |
|
Please add the QUERY method: https://datatracker.ietf.org/doc/draft-ietf-httpbis-safe-method-w-body/ |
|
The general feedback we get is that people prefer maps over arrays. Arrays infer ordering that isn't necessarily significant. Arrays are harder to modify. Personally, I don't feel very strongly about the issue. However, when editing the OpenAPI document in an editor that outlining, the key provides a very nice summary of the collapsed region. I used the term request because that is the term that HTTP uses. Over the past few iterations we have attempted to move OpenAPI closer to the terminology and semantics of HTTP. |
Order is incredibly important for us. I'll repeat that again, WE MUST KNOW THE ORDER OF OPERATIONS. Users that use our tools need to tell us the order, so either order is defined in the spec or we need arrays. And our tool is not the only one, it isn't like I'm saying "this one little edge case, for our needs, let's change everything", but this is an actual problem. Order does matter, and it matters to some non-zero set. We lose that. There are tons of clients in the world, it doesn't make sense to optimize for one (i.e. the UI editor) at the expense of all others. Sure editing maps is easier, but we lose actual value and features by doing so. So let's compare:
One is a need, the other has a workaround. Why wouldn't we support the value and not disable that. Also to the point:
Any editor that is doing this is deciding on arbitrary semantics, they can just as easily look at the |
The OpenAPI specification development process is an open one. https://github.com/OAI/OpenAPI-Specification#participation You are welcome to contribute. You might find you are more successful at influencing the direction if you try and avoid describing other people's efforts as madness though :-) |
x-mytool-sequence: 1 Just because one tool needs to be able to present content in some user defined order, doesn't mean that the right solution is to chose a JSON array to represent the ordering. Maybe the user doesn't want the ordering to appear in the way that it is added to the API description. There are pros and cons to every design choice. The use of arrays in OpenAPI 3.x for parameters has been challenge for a number of scenarios. It makes the work being done on Overlays considerably more difficult, for example.
You're right. Linters don't care about the order. Client code generators don't care. Server code generators don't care about the order. Payload validators don't care about the order. We can't just optimize for the document generators. But your point is valid and it is something we should consider. |
requests and methods is not actually 1:1. One of the reasons for introducing requests was because we regularly get asked to allow creating multiple operations for the same HTTP method. Requests will allow us to do this because they are discriminated on more than just method. Requests could be distinct based on URL parameters, HTTP headers, or methods, or possibly even values in the payload. This will allow people who are using HTTP to do RPC APIs to be able to describe their APIs. |
Ha, arguably all of these could care about the order. There are far too many linters out there that that complain about the order of imports or the order of methods in a class. The same goes for the other ones as well. Order of request properties. Can you imagine code generators creating method arguments not in a stable order?! Sure our solution can add Here's another problem with the Responses is weird because they can be sorted by their status code, arguably the keys for that object could be
Cool! I don't really care about the naming, so that was an unnecessary tangent I may have led us down. For instance our tool doesn't care what's in the path string, which allows most of this flexibility today as long as it is contained in query parameters. But I can imagine a similar need for header discriminators. And arguably separating |
handrews
added
the
registries
|
OK I'm going to ignore all the Moonwalk stuff which belongs in the Moonwalk repo, where there are discussions for various things including objects vs arrays and ordering. @darrelmiller it sounds like endorsing an Alternatively, we could actually allow additional non- @OAI/tsc review request: What is the best path forward in 3.x? |
|
As @karenetheridge suggested, in 3.x
In Moonwalk I'd lobby for using a |
|
I understand that the topic of this issue is "Support all HTTP Methods" and this will probably be implemented in moonwalk. But wouldn't it be possible to create an in-between solution, for instance API Spec 3.2 which adds just a few of the most requested methods like SEARCH and QUERY? I think these methods are really useful and fall within the scope of REST. It would be easy to implement and the tooling could be available quickly. On the contrary if we have to wait for moonwalk + tooling we will be several years out. Let's be pragmatic here, We've been waiting patiently for years on this and in this information age can we really justify waiting several more years if it can be implemented in a matter of months in a 3.2 spec in the mean-time? |
|
@Richie765 can you point to places where SEARCH and QUERY are implemented? And is that WebDAV SEARCH (I think we're rightfully wary of getting involved with WebDAV) or a different SEARCH, and how do we tell/enforce the difference? I think one reason this has never gained traction is that QUERY still doesn't have a spec and it's not clear (to us) that there's enough usage to define consistent behavior. I think if QUERY ever made it to RFC it would be quickly adopted here. I think most of the other potential methods are either WebDAV or don't have clear use cases for description (CONNECT). |
I feel like this may not be a full justifiable argument. It doesn't get usage because technologies don't support it. Technologies don't support it because people aren't using it. People don't use it because there is no spec. There is no spec because people don't use it enough. Please let's make the world we want to enable to live in and not wait for others to do something that they are totally incentivized against. If you don't believe there is sufficient usage to tell us how it works, there's an RFC already underway, does that answer any confusion that you believe still exists? |
|
@wparad the reason I'm bringing up the stable published spec issue is that it impacts how much of a challenge support will be for implementors. Our primary concern with 3.2 is that it add significant value with minimal implementation cost (so we don't have another "minor" release that takes 3-4 years to implement, although 3.1 was always viewed as an unfortunate but necessary special case). Now, obviously, we don't have to have a stable published spec to use something (ahem, JSON Schema...), but it is something that people bring up and we need to have an answer for it. So the reason I asked about usage is that if we can point to some reasonable number of APIs that implement it consistently enough that OAS support would be straightforward, then that's one way out of the chicken-and-egg problem. On the other hand, if there are QUERY implementations out there but they somehow contradict each other, that's a problem for OAS implementors.
I don't know one way or the other, that's why I'm asking the person who said it's in use and therefore we should support it. I would love to have time to research every point everyone brings up in an issue, but I don't, so when someone seems they might know, I ask them. 3.2 is very much a "do no harm" release in my view. If we mandate QUERY support, but the usage of QUERY in the wild is not consistent enough for that support to be succesful, that would be harmful. It would create implementations that can only work with some usages of QUERY, frustrating those dealing with a QUERY usage that doesn't match what some particular implementation chose. We need to not introduce interoperability problems of that sort in our spec. If you are frustrated with the lack of spec for QUERY, I suggest joining that effort. |
|
As a company that desperately wants to use QUERY and as one that has more than one tool in the openapi.tools website, this would be trivial for us to support predictable named additional verbs. Supporting all verbs is not trivial, but adding N more is incredibly easy. As far as we can tell on both sides, everyone wants this. No one is against it, and there is no confusion (from my limited experience) on how this would work. Pleas, please have support for it (/them) in a 3.2 version. |
|
I was under the impression that there already was a spec for QUERY but I see now it is just a draft. I could not find an API that yet uses QUERY (I only did a quick search though). But it is easy to find API's that use GET with a request body (Elasticsearch) or use POST to retrieve data (GraphQL, SOAP). In these cases it is clear to me QUERY would be a better option. It is simply not realistic to cram this kind of queries into URL parameters. For this is why QUERY is coming into the picture. I think this just common sense but the creation of these standards is just not very fast. I understand the importance for established standards but at this stage the IETF draft is already at a 3th publishing. Let's reverse the question. What is against adding query into OAI 3.2 as an experimental/draft feature. What could be a stronger argument than opening a path to eliminate incorrect usage of GET/POST. |
|
To make one thing clear: I'm not the person who will decide whether this goes into 3.2 or not. I'm mostly trying to anticipate what questions would come up on a weekly call when we discuss this request as we do 3.2 planning. @wparad @Richie765 what slightly concerns me about your most recent comments is that it feels a bit like you are looking to the OpenAPI Specification to help get QUERY out into the wild. That really should not be our role: that is the job of the IETF. I don't know why that RFC is still in draft (I'm not entirely sure how active it is, although the last time I asked someone who might know, they thought it was still active even if currently expired). I went and read the current QUERY draft, and there are some interesting subtleties to it. I do wonder if one reason for the hesitation is to try to be more clear about query media types than the PATCH RFC was about patch media types (I remain amazed at how few people even know about patch media types and I suspect the defined semantics of the response are also not necessarily what people expect. It's not semantically equivalent to a GET because it doesn't have the same correspondence between the URI and the representation (which is the entire point of QUERY, so that makes sense). Anyway, my point is not to debate the QUERY RFC but to note that it's not quite as straightforward as it might seem at first, and while I would strongly prefer to set things up so that if QUERY makes it to RFC status, it can be used in OpenAPI in accordance with that RFC without us having to do an update. But I suspect there will be concerns over getting ahead of the IETF process here. |
|
Just allergic to arguments that I struggle to follow. However, I also don't think it being in the 3.2 spec would make significant enough impact to justify having that perspective. The thing that will make it happen is cloud providers supporting it, with or without the QUERY RFC. I will say, I can't see ambiguity in the QUERY spec having a meaningful impact to adding the 7 characters to the allowed methods |
|
@handrews I also find this looking for nails at low tide. I can't see the relevance of it. All the HTTP methods are similar and they can be used in many different ways with different body content types, headers, etc. It is up to the application to decide what is correct. For one application it will be JSON, for another a text-based query language, CSV, or whatever is suitable. OpenAPI is used as an API description language to generate documentation, mock servers, API clients, etc. OpenAPI does not dictate how we should use the methods exactly. It doesn't do it for POST, GET, etc so why should it be a concern. Let's get back on track to the issue at hand. I thought it was already decided that in OpenAPI standard 4.0 ALL HTTP methods would be supported (hence the title of this issue). This is the reason I am here and nothing else. I already described important use-cases. The draft specs are in their 3rd iteration. In addition I like to emphasize it is common that software supports draft standards as experimental features. For instance I was recently working on SSL ESNI, this is still just a draft after many years but it is supported by all browsers and many web-servers. This happens all the time and is part of how things work in the industry. Anyways I don't intend to spend much more time on this. I think I've done my best it is now up to you guys to make a decision whether you're gonna make the 1 line change or not. |
|
I expect this will be looked at for 3.2. I was trying to flush out more points in favor prior to discussing it with the TSC, but it does not feel like anything has moved since this discussion last paused. I personally lean towards including more, and dislike |
|
@handrews Ok thanks for that and for discussing it with the TSC, let's see what comes out of that. I think in the end it boils down to the question if and how OAI can/will incorporate draft standards. If you want to play a role in progress or stand on the sidelines and watch others doing it first. Well, the rest has been said already. |
|
According to RFC9110, 9. Methods the request method is method = token
token = 1*tchar
tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
"^" / "_" / "`" / "|" / "~" / DIGIT / ALPHAand
This means we could allow Patterned Fields for the Operation Object with
and some restrictions:
This would allow to add Sanity check:
|
|
@ralfhandl thanks for the research! The explicit inclusion in Node.js seems like good evidence for usage, even if we don't know quite who is using it. I think we might need to allow the existing methods to start with a lower-case letter for compatibility purposes... while I get wanting to avoid having |
|
I've added this to the 3.2.0 milestone- this does not mean that it will necessarily be included, but does ensure that we look at it as we plan the release. |
Feature Request
OpenApi support for all http methods
RFC 2616 updated by RFC 7231 (errata list for 7231)
RFC 2518 updated by RFC 4918 and RFC 5689 for MKCOL
RFC 3253 (errata list for 3253)
RFC 3648
RFC 3744 (errata list for 3744)
RFC 5323
draft ietf httpbis safe method w body 03
draft snell link method 01
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.
The text was updated successfully, but these errors were encountered: