3.1 Choose the HTTP resource wisely

First of all, your life and the life of your package’s users will be easier if the web service you’re wrapping is well maintained and well documented. When you have a choice, try not to rely on a fragile web service. Moreover, if you can, try to communicate with the API providers (telling them about your package; reporting feature requests and bug reports in their preferred way).

3.2 User-facing grace (how your package actually works)

0. If you can, do not request the API every time the user asks for something but cache data instead. No API call, no API call failure! 😉 To remember answers within a session check out memoise. To remember answers across sessions, see webmiddens, and approaches presented in the R-hub blog post “Persistent config and data for R packages”. Caching behavior should be well documented for users, and there should probably be an expiration time for caches that’s based on how often data is updated on the remote service.

1. Try to send correct requests by knowing what the API expects and validating user inputs; at the correct rate.

• For instance, don’t even try interacting with a web API requiring authentication if the user does not provide authentication information.
• For limiting rate i.e. not sending too many requests, automatically wait or, if the API docs allow you to define an ideal or maximal rate, set the request rate in advance using the ratelimitr package.

2. If there’s a status API i.e. a separate API indicating whether the web resource is up or down, use it. If it tells you the API is down, stop() with an informative error message.

3. If the API indicates an error, depending on the actual error,

   • If the server seems to be having issues, re-try with an exponential back-off.

   • Otherwise, transform the error into an useful error.

   • If you used retry and nothing was sent after the maximal number of retries, have an informative error message.

That was it for aspects the user will care about. Now, what might be more problematic for your package’s fate on CRAN are the automatic checks that happen there at submission and then regularly.

3.3 Graceful vignettes and examples

4. Pre-compute vignettes in some way. Don’t use them as tests, they are a showcase. Of course have a system to prevent them from going stale, maybe even simple reminders (potentially in the unexported release_questions() function). Don’t let vignettes run on a system where a failure has bad consequences.
5. Don’t run examples on CRAN. Now, for a first submission, CRAN maintainers might complain if there is no example. In that case, you might want to add some minimal example, e.g.

if (crul::ok("some-url")) {
  foo_bar() # some eg that uses some-url
}

These two precautions ensure that CRAN checks won’t end with some WARNINGs e.g. because an example failed when the API was down.

3.4 Graceful tests

We’re getting closer to the actual topic of this book!

6. Read the rest of this book! Your tests should ideally run without needing an actual internet connection nor the API being up. Your tests that do need to interact with the API should be skipped on CRAN. testthat::skip_on_cran() will ensure that.
7. Do not only test success behavior! Test for the behavior of your package in case of API errors, which shall also be covered later in the book.

3.5 Conclusion

In summary, to have a graceful HTTP package, make the most of current best practice for the user interface; escape examples and vignettes on CRAN; make tests independent of actual HTTP requests. Do not forget CRAN’s “graceful failure” policy is mostly about ensuring a clean R CMD check result on CRAN platforms (0 ERROR, 0 WARNING, 0 NOTE) even when the web service you’re wrapping has some hiccups.