swagger-ui: GET method doesn't support body payload

+1

The HTTP spec does not forbid using body on a GET.

De facto, a very popular server product (ElasticSearch) does use the body on a GET.

Regardless of previous convention, the scenario should be supported.

This is fallout from the move from “POST is for form submissions, GET is for page requests” way of thinking to “JavaScript calls RESTful APIs through AJAX and updates the DOM” way of thinking.

Logically, a request can be a GET (I am retrieving an entity) while the specification of the entity to retrieve can be too complex to put in the path or url parameters and so the right place to put it is in the body. (ie a JSON object)

I think it’s a good idea. The same principle works elastichsearch. This solution is convenient when you need to maintain the concept of REST API (read, create, update, and delete), and for the GET request is necessary to pass a sufficiently large amount of data. For example, imagine an request report with lots of fields for aggregates, filters and sorts. Yes, even given the fact that all IDs have UUID format.

Yes, it is not as specified, but you are developing a tool, how to use it already solves the developer. Trimming functionality you force developers to do more possible bad decisions or make patches on your project.

Read the HTTP spec. It specifically says that a body in a GET is not forbidden, however the server must ignore the value. We’re not adding support for that in the tool in the short term.

Body payloads are not supported by swagger in a GET operation, and is typically not supported by any server frameworks, even though the http specification is vague about supporting them.

Perhaps you are looking at an older version of the spec?

In the current spec: RFC 7230 3.3

The presence of a message body in a request is signaled by a
Content-Length or Transfer-Encoding header field.  Request message
framing is independent of method semantics, even if the method does
not define any use for a message body.

The sender’s allowed to send a body in a GET.

RFC 7231 4.3.1

 A payload within a GET request message has no defined semantics;
 sending a payload body on a GET request might cause some existing
 implementations to reject the request.

I don’t see any mandate to disregard the body of a GET.

A payload within a GET request message has no defined semantics; sending a payload body on a GET request might cause some existing implementations to reject the request.

I don’t see any mandate to disregard the body of a GET.

That’s pretty much the definition of undefined behavior. In theory adding a body to a GET request could turn it into a DELETE request and it would be in-spec.

https://en.wikipedia.org/wiki/Undefined_behavior

So yes, it’s absolutely allowed to add a body to a GET request, but no you shouldn’t and rely on anyone to accept it. Swagger-ui is also totally in-spec by rejecting it. ElasticSearch relying on this is simply bad design.

I don’t think enforcing “good practices” is the business of an UI tool. Whether the request body is discarded or not should be decided on the server side. In any case, allowing the user to input a request body, then discarding it without any warning is a bad idea. At least show a warning as other people suggested.

IMHO this should be reopened.

In the RFC, request bodies of GET (& co) is “undefined”. In swagger/openapi, it’s “forbidden”. IMHO this is overstepping the responsibility of a spec tool.

This is of course not harmless. Typical use cases are your elastic search queries, with for example:

curl -XGET 'localhost:9200/mobile/_search?pretty' -H 'Content-Type: application/json' -d'
{
  "query":{
    "bool":{ 
      "must":[
         {"terms":{"brand":["micromax","samsung"]}}
      ] , 
      "should":[
         { "range": { "price": { "gte": 6000, "lte": 10000 } } },
         { "range": { "price": { "gte": 16000, "lte": 30000 } } }
      ]
    }
  }
}

…but also covers all range of queries which aren’t simplistic and need a bunch of dynamic parameters.

For these, the choice boils down to “not use swagger/openapi” or “use POST method” which is clearly semantically wrong.

It’s not about whether people “should” use a body with GET.

It’s recognizing the reality that some people do it despite the fact that they shouldn’t.

And not going out of our way to prevent them from modeling their “wrong” design with swagger.

It’s not swaggers job to enforce convention and that’s the role being assumed here. The spec does not forbid what elasticsearch is doing here, and swagger is actively forbidding what the spec itself does not. That’s a mighty high horse to think you know so much better than everyone else to impose your interpretation of an ambiguous spec.

On Tue, Mar 1, 2022, 11:27 AM Evert Pot @.***> wrote:

Just in case people are still confused why GET should not have request bodies, I wrote even more words on my blog: https://evertpot.com/get-request-bodies/

— Reply to this email directly, view it on GitHub https://github.com/swagger-api/swagger-ui/issues/2136#issuecomment-1055782048, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAIQ4BON3R4IPTK26OQGMS3U5ZVSRANCNFSM4CC3WZNA . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

You are receiving this because you commented.Message ID: @.***>

Why does a documentation tool have such a strong opinion about how the services being documented are designed?

Note: apparently, it’s being changed soon:

https://github.com/OAI/OpenAPI-Specification/pull/1937

I really do think this is a case of dogma trumping common sense. The point of having a body in a GET is for complicated read-only operations. That is why Elastic Search uses it. The POST, PUT and PATCH verbs are for changing data. The fact that most applications and servers never had a need to implement body parsing for GETs is neither here nor there. The point is that fact should not go and change the design of the protocol. The protocol allows a body because you might need it to do a query. Lots of things from SQL to GraphQL could be put in the body. And lots of systems are broken today because they use POST for doing read-only stuff, which prevents them from being able to dispatch easily and appropriately on the HTTP verb, for instance for access control (no write = NO POST, PUT).

OpenAPI 3.0 has the say here. GET bodies SHALL be ignored.

Is there a possible compromise on this point? I work on internal API’s where GET bodies are particularly useful to implement complex semantic search over a collection of tree-like objects. The real issue with GET bodies is the behavior of caching proxies. Caching proxies do not generally allow GET bodies as an optimization.

But I do not think API design should be limited by the implementation details of caching proxies. It may be however that the UI should not offer this unless the swagger spec specifically identifies body characteristics?

Dude, just use POST instead of GET to solve the problem and after change to OpenAPI 3.1 😄

Heh, the issue is closed, any additional comments that come in are not really going to impact anything.

Here’s some information that people seem to be missing:

1. Swagger is not the spec. It’s a set of tools around the OpenAPI Specification. Swagger simply follows what OpenAPI says is or not allowed.
2. In OpenAPI 3.0, we decided to follow the HTTP spec more closely and remove support for payloads for GET, DELETE and so on.
3. In OpenAPI 3.1, we decided to go back on this change for the main reason that indeed many APIs are designed this way (this is not to say that we believe it’s the right approach).

So - you can complain about Swagger all you want, but it is not Swagger’s fault. If you’re using OpenAPI 3.0, you can’t describe payloads for GET operations. Nothing will change that. If you want to describe such operations, switch to OpenAPI 3.1.

While I do agree it should be discouraged, disallowing it is not the responsibility of swagger-ui. The spec allows it, so should you. The main reason is the max length of an URI is undefined and relies on the implementation of the server and all the hops in between. Complex search requests can easily be longer than 2048 characters, which is the “customary” maximum length, as has been shown multiple times already. Using the body here makes perfect sense, though you have to be very aware that you specification can break an application.

Just stating “use POST” is about as correct as stating “use a hammer on that screw” if you’re talking about adhering to a specification…

I ran into the same issue, trying to send a body to a GET against Elasticsearch (which it supports). I solved the issue by using a POST instead and configuring Swagger that way.

This is why we use Graphql instead of Swagger. There are complex scenarios you SHOULD send a request body to GET or instead you will need to use POST while you’re still 'GET’ting data from server. It was simply funny to see that a DOCUMENTATION TOOL enforces this kind of thing. 😄

I can’t speak for them, but my interpretation for the change for OpenAPI is:

“We acknowledge that this is terrible design and nobody should do this, but even so we want to support the people that having request bodies on GET”. It wouldn’t have been my decision, but I understand the motivation

@evert, agreed.

To clarify, here’s what OpenAPI 3.0 says about this:

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.

@jconti tbh, I don’t see that happening. In 3.0, we have explicitly expressed that payloads with not work for GET, DELETE and such.

the answer is there -> https://github.com/swagger-api/swagger-ui/issues/8682#issuecomment-1552927858

TLTR : Swagger UI v5 do not support GET with body payload

using Swagger UI v5.0.0

It still fail on GET with body payload , this is no supported (even with openapi 3.1 support ) ? thanks

That’s a mighty high horse to think you know so much better than everyone else to impose your interpretation of an ambiguous spec.

I consulted with the actual authors of the HTTP spec and they share this point of view. I’ve contributed to the new phrasing in the upcoming HTTP spec to better clarify this. These changes were accepted and it will be a lot less unclear. But sure… attack me instead of my arguments. Can this thread be locked?

I don’t think you should forcibly forbid people to do stuff that is explicitly not defined. We’ll probably end up using post as keyword and then just in the description write that GET should be used…

Swagger Editor has been changed and will work the same as swagger-ui.

Swagger editor supports this functionality by converting the body into url encoded query string. Is this a possible approach to update the Swagger UI?