pass multi-value parameters as vectors to GET

[mkoohafkan]

GET requests can handle multi-value parameters, although there is no defined standard on how to do it. httr2 currently supports multi-value parameters when you define them explicitly as separate arguments:

request("example.com") |>
  req_url_query(foo = 1, foo = 2) |>
  req_dry_run()

#> GET /?foo=1&foo=2 HTTP/1.1
#> Host: example.com?foo=1&foo=2
#> User-Agent: httr2/0.2.3 r-curl/5.1.0 libcurl/8.3.0
#> Accept: */*
#> Accept-Encoding: deflate, gzip

But it would be nice if you could pass multi-value parameters as vectors and have httr2 do the work of forming the url with multiple entries for the parameter(s):

# desired  behaviour
request("example.com") |>
  req_url_query(foo = c(1, 2)) |>
  req_dry_run()

#> GET /?foo=1&foo=2 HTTP/1.1
#> Host: example.com?foo=1&foo=2
#> User-Agent: httr2/0.2.3 r-curl/5.1.0 libcurl/8.3.0
#> Accept: */*
#> Accept-Encoding: deflate, gzip

I could see the other common form of multi-value parameters being handled via I():

# desired  behaviour
request("example.com") |>
  req_url_query(foo = I(c(1, 2))) |>
  req_dry_run()

#> GET /?foo=1,2 HTTP/1.1
#> Host: example.com?foo=1,2
#> User-Agent: httr2/0.2.3 r-curl/5.1.0 libcurl/8.3.0
#> Accept: */*
#> Accept-Encoding: deflate, gzip

[hadley]

I see the appeal in doing the first form automatically since it's bit of a hassle to do by hand, but the second is easy enough to do with paste() that I don't think it's worth wrapping into httr2.

[mgirlich]

@hadley To me it feels quite unexpected that req_url_query(foo = c(1, 2)) is the same as req_url_query(foo = 1, foo = 2). I would rather expect the second form, i.e. the same as req_url_query(foo = "1, 2") (but I am also much more familiar with this form than the other).

And comparing

req_url_query(!!!set_names(1:2, "foo")) # `req_url_query(foo = 1, foo = 2)`
req_url_query(foo = paste0(1:2, collapse = ",")) # `req_url_query(foo = "1,2")`

I think that both forms are quite easy to generate (though one has to know about !!!).

[hadley]

Yeah, I don't think that most people know about !!!, and you also have to know about set_names(), since setNames() isn't vectorised, and even setNames() is not commonly known.

Maybe we should make it more explicit with a helper?

[mgirlich]

What about adding an argument to req_url_query() which allows you to control which form you want? It could default to error if you supply a vector with more than one element. This would be very explicit and easy to use.

[hadley]

Yeah, I like that — could be multi = c("error", "splat", "concat"). (Although we might need a better name than splat)

[jonthegeek]

Yeah, I like that — could be multi = c("error", "splat", "concat"). (Although we might need a better name than splat)

I've seen "explode" used in api descriptions for "splat". I can't find where that's defined but I think it's either an OpenAPI or jsonschema official term.

[mkoohafkan]

+1 for a multi argument. if you wanted to allow complete customization you could let the multi argument accept a function. Since there is no defined standard for multi-value parameters there might be some APIs that e.g. delimit arguments with ; instead of ,. Might be overkill though.

[hadley]

Accepting a function is probably overkill, but it would be nice use case for this function I'm working on: https://design.tidyverse.org/explicit-strategies.html#escape-hatch.

[hadley]

https://swagger.io/docs/specification/serialization/ calls it explode so that sounds like a good name. I've also added "pipe" as an option, as that seems reasonably common.