Make use of x-form-urlenoded parameters more explicit

Make use of x-form-urlenoded parameters more explicit

Description

If have to send requests to an API that I do not control, where some parameters are sent inside the URL and others are sent as x-form-urlencoded body. I don’t see an easy way to do this with fuel. In my opinion this is caused by the rather implicit handling of parameters.

Proposed Solution

Add a new function urlEncodedBody that sets a body explicitly with the correct headers, like jsobBody.

Example:

FuelManager.post("path/", listOf("param" to 1))
    .urlencodedBody(listOf("foo" to "foo", "bar" to "bar"))

would set the Header Content-Type : application/x-www-form-urlencoded and set a body `Body: “foo=foo&bar=bar”.

Additional change

Remove automatic encoding in the x-form-urlencoded body. In my opinion, this is bad design anyway. The parameters argument should not be used for two independent features. To a developer, those three lines look very similar, yet the parameters behave “arbitrarily”.

FuelManager.get("path/", listOf("param" to 1))
FuelManager.post("path/", listOf("param" to 1))
FuelManager.post("path/", listOf("param" to 1))
    .jsonBody("{}")

Additional context

I find it hard to understand when Fuel puts parameters in the URL or encode them as x-form-urlencoded body in general. I have used Fuel for almost a year know on a daily basis and always have difficulties to remember how those parameters are encoded in POST request.

[adiykehler]

Thanks for your quick reply.

That “arbitrary” behaviour is also how your browser works. I like the addition of the urlencodedbody, but the current behaviour is not bad design.

It feels arbitrary to me, because I’m not familiar with browsers or Javascript. If this is common style in HTTP libraries, then ignore my additional change request. I’m OK with that.

[kittinunf]

I think it is a good addition to the library, though I don’t think the current design is that bad, however, we tried to cover the common use-cases.

So there might be some cases that we don’t support! All in all, I am up for this change though.