Why don't toQueryParam or toUrlPiece actually url-encode the data?

[saurabhnanda]

I was trying to write my own ToHttpApiData instance for a newtype wrapper over text, and ended up looking at the existing instance for Text and was surprised to find that it isn't really url-encoding the data. Why is this the case? Isn't the idea of this type-class to convert a value to be safe for usage in URLs (either as path fragments or query-params)?

If ToHttpApiData is not supposed to emit url-encoded stuff, what is the type-class/function/mechanism that does it?

[fizruk]

@saurabhnanda that is a great question! I think we have only covered it in some discussions on GitHub, but have not moved any of it into Haddock documentation.

First, if you're looking for a function that does URL-encoding, see toEncodedUrlPiece.

http-api-data basically tries to parse Text/ByteString that is received via HTTP APIs.
In the spirit of "let a function do one job well" we don't try to perform the decoding/encoding (whether it be URL-encoding or UTF8 or something else). At least not in the class methods.

This can be beneficial for when your web framework already does encoding/decoding for you.
Or when you encode/decode the whole query string or request body.

Hope this answers your question :)

[ocharles]

This can be beneficial for when your web framework already does encoding/decoding for you.

I just ran into this from servant(-client) and was pretty surprised. A route that Captures Text doesn't encode it at all!

[saurabhnanda]

I'm running into this issue again. Till the time there is a better solution available for #143 , I'm converting my Haskell record to a JSON and using that for toQueryParam & parseQueryParam

Should I be url-encoding this JSON, or not?

If I don't urlencode it, the JSON shows up as-is when using safeLinks from servant.