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/ |
|
That's not quite what I was trying to say about Overlays although it's certainly a valid point and for an Overlay that's used for multiple OpenAPI descriptions, it would make upgrading those versions harder. The use case I tried to mention on the call is where an Overlay is used to add an operation (something like the approach here: https://apichangelog.substack.com/p/using-openapi-overlays ) - because we're changing what syntax we're allowing, I think this will get messy for a lot of existing pipelines, and will be a lot messier by the time many people are able to upgrade to 3.2 where Overlays is already seeing adoption in the 3.1 space. Looking at the problem again, I think my preferred options are:
|
|
Overlays cannot be used as a migration tool. The existing content of the document is not available as an input in a (v1) Overlay. |
|
I'm concerned about Overlays suddenly adding even more restrictions on what we can and cannot do in a minor version change. This is going to make it very hard to deliver Moonwalk in meaningful increments. While this limited case can be worked around, we will not be able to work around the identical concern when we revamp parameters for 3.3. The entire point is that the current parameter syntax is too complex and rickety to extend further. If people want to use new parameter features in 3.3, they will need to migrate to a new way of doing it for that operation. There is always a migration cost. This is not so much about HTTP methods as it is figuring out how to amortize the migration cost effectively. We should also look at what could be done on the Overlay side in an Overlay 1.1 (which I know was not in the plan, but perhaps it should be if it's going to constrain what the OAS can do). Adding limited semantic selection capabilities of some sort would also solve this by separating the meaning of the overlay from the exact syntax of the OAS. Again, change has a cost. We want to amortize the big-bang change of Moonwalk across steps in 3.x (because we've seen how hard big bang changes are), and we want to make sure that none of our specs (OAS, Arazzo, Overlay) become a problematic constraint on the other. That means considering whether a difficult interaction is best fixed in one vs the other spec. This does not mean that all migration costs should be pushed into 3.x. If something (possibly even a parameters revamp) is still too "big bang" in 3.x then we need to figure out whether to move ahead or to make the 4.0 big bang bigger. I don't know the answer to that at this stage. Getting back to HTTP, if this is a problem for Overlays, the solution might lie in changing Overlays rather than restricting OAS. And again, we should not think of this as a one-off. As a one-off, it doesn't much matter. But that is the problem with a lot of the OAS (ahem, parameters). Too many one-offs that add up to a lot of complexity and no patterns to make it easier. |
|
I'd like to tie two of my previous comments together here. I previously mentioned that at the document (DOM) layer, the different options under consideration are significant, but at the semantic layer (ADA), they are all the same. This is where I think it would be good to start aligning OAS, Arazzo, and Overlays in terms of how we think about changes in any one of these three impacting the other two. We want 4.0 (Moonwalk) to be build around the DOM/ADA (document vs semantic layer) concept, and we need to start introducing it now to get the community ready for it. To me, this means leveraging the idea of two layers when we want to make a change like this. And for Arazzo and Overlays, both of which operate on an OAD by different query/selection languages, this means moving their divergent mechanisms closer to a unified semantic level. I do NOT mean moving everything to a semantic level immediately. The goal is to introduce this gradually. What this means is that we can use methods as a trial introduction of the two-layer idea. Describe it in 3.2 in such a way that encourages tools to abstract away the difference between how "old" and "new" methods work- regardless of the syntax chosen. There will always be some syntactical awkwardness no matter what we choose (unless we continue to restrict to a pre-defined set, but I'm going to fight very, very hard against that option). So we want to discourage tool developers from reifying that awkwardness, and encourage them to instead treat HTTP methods (and the Operations they represent) as semantic elements within a Path Item, not field names in a JSON/YAML object namespace. This can go with tweaks to the other specifications to require a limited semantic match. What that means is not clear, and no doubt will produce a lively discussion. But again, cautious incrementalism is the goal here. Let's use 3.2 (and perhaps 1.1 of the other two specs? paging @frankkilcommins to get an Arazzo perspective) to try out a tiny bit of semantic abstraction with HTTP methods, and see how we can make use of that in the other specs. This way, when we get to the much more complex abstractions needed to incorporate 3.3 and later, we'll have some idea of what works and what does not. A small feature like HTTP method expansion is an ideal way to try out this two-layer concept and figure out its implications across all of our specifications. |
|
I think there is a risk that we are overcomplicating this request for additional HTTP method support that could make it difficult to make available in a timely manner. Let's pick a subobject name and allow additional method names there to meet the original issue requirements and maintain backward compatibility and an easy upgrade path in the 3.x branch. |
|
@lornajane I think there is a deeper issue here as I have said about compatibility, DOM/ADA, and how the three specs work together. I would like to discuss it at least a little more as we have not even addressed it in a meeting yet. |
|
@lornajane I'll also note that the position you're taking here makes my entire approach for 3.3 invalid. So if this is the direction we're going to go in, then we need to reconsider the 3.2 vs 3.3 split, because there's no point in doing the 3.3 I had envisioned. (this might be fine, it just needs to be considered) |
|
There is another wrinkle here, which is that people rely on the special Path Item Object To me, this is another reason to just have a new alternative alongside the old way, because the old way (between the problematically special If we have a new This could be a path. |
|
In today's Overlays meeting (which @lornajane was unable to attend), @mikekistler demonstrated how challenging it is to get the correct JSONPath expression to select a particular operation by method name and Operation Object field value. This naturally led into a discussion of how much more difficult it is to create that expression when a Path Item Object uses We talked about the possibility of a hybrid approach to introduce an experimental, limited mechanism for selecting operations. This could build on the existing JSONPath approach, e.g. using JSONPath to select the correct entry in the Paths Object but then being able to say "give me all operations" or "give me operations with field X set to value Y" semantically, so that the use of This discussion carried over into the Moonwalk meeting, where folks were in favor of using 3.2 to add an experimental semantic model for this specific area that would support that semantic model. @mikeschinkel noted that we'll need to define "experimental" formally in order to correctly set expectations around this. What we want is for tool vendors to be motivated to try this, but also to see that it is not locked-in and that there is an opportunity to influence htis before it becomes locked-in. I noted that formally defining "deprecated" is related to this, as both are ways to modify the compatibility guarantees. @mikeschinkel was kind enough to file #4325 to track this. I'm going to work on what a semantic model might look like and hopefully have something to show at the next TDC call on Thursday. It is trickier than it first appears because of webhooks and callbacks. |
|
Looping back around to this again, because I know we don't want to lose sight of it. The goal: support more HTTP methods; at a minimum add QUERY for 3.2, but more/all methods seems to be desirable. In the past we've taken the view that we're aiming to support RESTful API users only, but my impression now is that we're more open to letting people take responsibility for their own decisions rather than us introducing limitations in the specification. We currently have alongside other fields I propose that we add
As an additional note, there are a few mentions about Overlays being a blocker to some of the other proposed alternatives, and I don't see that as a fair reflection of the situation because there's nothing special about Overlays used in an API description pipeline. If a user has any OpenAPI transform steps in use, then any situation where an edit in one part of an API description causing knock-on changes in another part will be a problem. Plenty of teams have the odd mad regex in play, and they'd have the same surprises as an Overlays user. |
I fully agree, that is the least disruptive way forward
Here I disagree: Consistency with RFC9110 is more important to me than consistent "styling" within the OAS. Let's follow RFC9110, section 9 and avoid problems for API owners that use case-sensitive non-standard method names and rely on the API clients to use exact casing of these method names:
|
|
@ralfhandl I agree with your take, the new Object should follow RFC9110, not our earlier mistake. I'm dropping the other proposal in favor of your modification of @lornajane's proposal. I prefer
@lornajane I do disagree here. Overlays is our spec, and we have to establish what compatibility means when we control both specs. I'm still unhappy that this is imposing previously-unheard-of constraints on our compatibility story, which is already extremely restrictive. But I don't have the bandwidth to argue it now so I'm giving up on it for HTTP methods. But it is very different than people making ad-hoc tools. We need to have a clear policy on how our specs interact with each other, and we don't, and that's our problem. What other people assume in their ad-hoc tooling, despite their assumptions not being supported by the OAS at all, is not our problem in terms of formal guarantees. |
|
Hey everyone, |
|
I favor |
|
I can get down with |
|
@kevinswiber we definitely have people wanting to use other methods, or custom methods. Why the pushback? |
|
@handrews I was just doing one last call out for keeping it simple to bring us back around. We go design down rabbit holes sometimes. If folks are good moving forward, let's go. |
|
I'm happy to move forward, it was a long comment thread but I think I can summarise it as: we're going to add @baywet does this give you what you need? |
|
@kevinswiber @lornajane if we want to make One advantage is that over time, we could more easily survey for usage of |
|
@kevinswiber @baywet I think both of you have talked about writing a PR? I don't care who does it, but if neither of you have bandwidth just lmk and I'll add it to my queue. |
It does, I think the crowd here has reached a consensus, and I'm happy to work on that :) |
|
I just put together #4514 |
|
Do I understand correctly that it's just adding query? The request, over 5 years ago, was more than just query. So how many more years will it be until the next version? It seems to me that those developers and architects that wanted additional methods or operations or whatever we call them that it was not engrained in the spec but follows RFC9110. Methods always made sense to me as the spec refers to these verbs as Methods. 9.1 ... I'm still hung on the word ought, and not the use of MUST. This to me doesn't mean MUST and therefor clients "can" request other methods not defined in RFC9110. |
No, #4514 will add a fixed field OpenAPI-Specification/tests/schema/pass/path-item-object-example.yaml Lines 36 to 55 in cfdc4bc |
|
@ralfhandl thank you, no intention on being rude in my last post. Just confused when I read the PR. I didn't see the |
|
@ScotMeyer Sorry, I didn't find your comment rude in any way. I just wanted to play with the word "query" which to me has the the connotation of "demand". |
and others
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: