-
Notifications
You must be signed in to change notification settings - Fork 17
/
intro-general.Rmd
116 lines (77 loc) · 5.17 KB
/
intro-general.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
# (PART) Introduction {-}
# HTTP in R 101
## What is HTTP?
HTTP means HyperText Transport Protocol, but you were probably not just looking for a translation of the abbreviation.
HTTP is a way for you to exchange information with a remote server.
In your package, if information is going back and forth between the R session and the internet, you are using some sort of HTTP tooling.
Your package is making _requests_ and receives _responses_.
### HTTP requests
The HTTP request is what your package makes.
It has a method (are you fetching information via `GET`? are you sending information via `POST`?), different parts of a URL (domain, endpoint, query string), and headers (containing for instance your secret identifiers).
It can contain a body. For instance, you might be sending data as JSON.
In that case one of the headers will describe the content.
How do you know what request to make from your package?
Hopefully you are interacting with a well documented web resource that will explain to you what methods are associated with what endpoints.
### HTTP responses
The HTTP response is what the remote server provides, and what your package parses.
A response has a status code indicating whether the request succeeded, response headers, and (optionally) a response body.
Hopefully the documentation of the web API or web resource you are working with shows good examples of responses.
In any case you'll find yourself experimenting with different requests to see what the response "looks like".
### More resources about HTTP
How do you get started with interacting with HTTP in R?
#### General HTTP resources
* [Mozilla Developer Network docs about HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP) (recommended in the zine mentioned hereafter)
* (_not free_) [Julia Evans' Zine "HTTP: Learn your browser's language!"](https://wizardzines.com/zines/http/)
* The docs of the web API you are aiming to work with, and a search engine to understand the words that are new.
#### HTTP with R
* The docs of the R package you end up choosing!
* Digging into the source code of another package that does similar things.
## HTTP requests in R: what package?
In R, to interact with web resources, it is recommended to use `{curl}`; or its higher-level interfaces `{httr}` ([pronounced _hitter_ or _h-t-t-r_](https://community.rstudio.com/t/pronunciations-of-common-r-terms/1810/15)), `{httr2}` or `{crul}`.
Do not use RCurl, because it is not actively maintained!
When writing a package interacting with web resources, you will probably use `{httr2}`, `{httr}` or `{crul}`.
* `{httr}` is the most popular and oldest of the three packages, and supports OAuth.
`{httr}` docs feature a vignette called [Best practices for API packages](https://httr.r-lib.org/articles/api-packages.html)
* `{httr2}` _"is a ground-up rewrite of httr that provides a pipeable API with an explicit request object that solves more problems felt by packages that wrap APIs (e.g. built-in rate-limiting, retries, OAuth, secure secrets, and more)"_ so it might be a good idea to adopt it rather than `{httr}` for a new package. It has a vignette about [Wrapping APIs](https://httr2.r-lib.org/articles/wrapping-apis.html).
* `{crul}` does not support OAuth but it uses an object-oriented interface, which you might like.
`{crul}` has a set of [clients, or ways to perform requests](https://docs.ropensci.org/crul/articles/choosing-a-client.html), that might be handy. `{crul}` also has a vignette about [API package best practices
](https://docs.ropensci.org/crul/articles/best-practices-api-packages.html).
Below we will try to programmatically access the [status of GitHub](https://www.githubstatus.com/api/#status), the open-source platform provided by the company of the same name.
We will access the same information with `{httr2}` and `{crul}`
If you decide to try the low-level curl, feel free to contribute an example.
The internet has enough examples for httr.
```{r}
github_url <- "https://kctbh9vrtdwd.statuspage.io/api/v2/status.json"
```
The URL above leaves no doubt as to what format the data is provided in, JSON!
Let's first use `{httr2}`.
```{r}
library("magrittr")
response <- httr2::request(github_url) %>%
httr2::req_perform()
# Check the response status
httr2::resp_status(response)
# Or in a package you'd write
httr2::resp_check_status(response)
# Parse the content
httr2::resp_body_json(response)
# In case you wonder, the format was obtained from a header
httr2::resp_header(response, "content-type")
```
Now, the same with `{crul}`.
```{r}
# Create a client and get a response
client <- crul::HttpClient$new(github_url)
response <- client$get()
# Check the response status
response$status_http()
# Or in a package you'd write
response$raise_for_status()
# Parse the content
response$parse()
jsonlite::fromJSON(response$parse())
```
Hopefully these very short snippets give you an idea of what syntax to expect when choosing one of these packages.
Note that the choice of a package will constrain the HTTP testing tools you can use.
However, the general ideas will remain the same.
You could switch your package backend from, say, `{crul}` to `{httr}` _without changing your tests_, if your tests do not test too many specificities of internals.