Better documentation for modify_url()

I haven't used curl in a long time, so I'm relying on the httr documentation to help me know how to make API calls. I suspect the primary userbase of this package is people who are really familiar with curl, so this may not be something the majority of users need, but I could use a bit more documentation for modify_url().

By searching for the list of parameters I found a general page about URLs that explained a lot of the terms. Then, by searching for the most relevant sounding ones on GitHub, I was able to find an example of using path that I could generalize to my usecase. I could imagine a number of approaches to the documentation:

explanations of the arguments directly on the page
examples of their use directly in the documentation
pointers to code demonstrations that use the relevant arguments
... or even just a link to a general page like the one I found

In case it is at all useful (either for the httr team or other novices searching for examples), here are two API calls I have figured out how to make.

First, an API that uses the standard &parameter=value convention for APIs,

res <- GET("https://boardgamegeek.com/xmlapi2/thing?",
  query = list(type = "boardgame", id = 13, comments = 1)
)

Then, another one that just uses slashes in the URL,

res <- GET(
  modify_url("https://ridb.recreation.gov/", path = c("api", "v1", "recareas", "2837")),
  add_headers(
    accept = "application/json",
    apikey = "yourkeyhere"
  )
)

My guess is that both of these calls could be cleaned up if I understood curl/httr better, but they do seem to be functional.

r-lib / httr

Better documentation for modify_url() #713