Skip to content
Permalink
Browse files

Doc/vignette revision; assorted modernizations

  • Loading branch information...
nealrichardson committed Aug 27, 2018
1 parent bfc25a4 commit a534d3e9d03dad6fae053d39a6ee2eefa4eaa87b
Showing with 39 additions and 27 deletions.
  1. +1 −3 .travis.yml
  2. +1 −0 DESCRIPTION
  3. +1 −1 NEWS.md
  4. +1 −2 R/cache.R
  5. +3 −1 README.md
  6. +8 −8 _pkgdown.yml
  7. +1 −1 pkgdown/extra.css
  8. +23 −11 vignettes/httpcache.Rmd
@@ -4,7 +4,5 @@ r:
- oldrel
- release
- devel
r_github_packages:
- jimhester/covr
after_success:
- Rscript -e 'library(covr);codecov()'
- test $TRAVIS_R_VERSION_STRING = "release" && Rscript -e 'covr::codecov()'
@@ -22,6 +22,7 @@ Imports:
httr (>= 1.0.0),
utils
Suggests:
covr,
httptest (>= 3.0.0),
knitr,
spelling
@@ -54,5 +54,5 @@ Logging improvements:

## httpcache 0.1.0

* Extract code and tests from the [crunch](http://crunch.io/r/crunch/) package
* Extract code and tests from the [crunch](https://crunch.io/r/crunch/) package
* Document and export functions for caching, invalidating, and logging
@@ -1,7 +1,6 @@
caching <- function () {
## Default should be on, so if httpcache.on isn't set, return TRUE
opt <- getOption("httpcache.on")
return(is.null(opt) || isTRUE(opt))
isTRUE(getOption("httpcache.on", TRUE))
}
#' Manage the HTTP cache
#'
@@ -25,7 +25,9 @@ The pre-release version of the package can be pulled from GitHub using the [devt

## Getting started

Working with `httpcache` is as simple as loading the package in your interactive session or script instead of `httr`, or, in package development, importing the HTTP verb functions from `httpcache`. `GET` responses are added to the local query cache until `PUT`, `PATCH`, `POST`, or `DELETE` requests trigger cache invalidation, or until you command the invalidation explicitly. See `vignette("httpcache")` for examples of the HTTP cache in practice.
Working with `httpcache` is as simple as loading the package in your interactive session or script instead of `httr`, or, in package development, importing the HTTP verb functions from `httpcache`. `GET()` responses are added to the local query cache; `PUT()`, `PATCH()`, `POST()`, and `DELETE()` requests trigger cache invalidation on the associated resources. You can override that default cache invalidation, and you can command the invalidation explicitly, with the invalidation functions `dropCache()`, `dropPattern()`, and `dropOnly()`. `clearCache()` wipes the cache completely.

See `vignette("httpcache")` for examples of the HTTP cache in practice.

## For developers

@@ -1,19 +1,19 @@
url: http://enpiar.com/r/httpcache
url: https://enpiar.com/r/httpcache
navbar:
title: httpcache
type: default
left:
- text: Get Started
href: articles/httpcache.html
- text: Reference
href: reference/index.html
href: reference/
- text: News
href: news/index.html
href: news/
right:
- icon: fa-github fa-lg
href: https://github.com/nealrichardson/httpcache
- icon: fa-home fa-lg
href: http://enpiar.com
href: https://enpiar.com
reference:
- title: Main functions
contents:
@@ -23,15 +23,15 @@ reference:
- uncached
- title: Logging
contents:
- startLog
- logMessage
- halt
- loadLogfile
- logMessage
- requestLogSummary
- startLog
- cacheLogSummary
- title: Cache API
contents:
- buildCacheKey
- cache-api
- cache-management
- cache-api
- saveCache
- buildCacheKey
@@ -1 +1 @@
@import url("http://enpiar.com/r/httptest/extra.css");
@import url("https://enpiar.com/r/httptest/extra.css");
@@ -1,13 +1,18 @@
<!--
%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{Improving API client performance with httpcache}
-->

# Improving API client performance with `httpcache`
---
title: "Improving API client performance with httpcache"
description: "This vignette presents the main features of the httpcache package, showing how to use the cache-aware HTTP functions, how to invalidate cache as needed, and how to use logging to assess the performance of the cache."
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Improving API client performance with httpcache}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---

`httpcache` provides the
HTTP verb functions `GET()`, `PUT()`, `PATCH()`, `POST()`, and `DELETE()`, which are drop-in
replacements for those in the [httr](http://httr.r-lib.org) package. So, to take advantage of these cache-aware functions, all you need to do is load `httpcache` instead of `httr`, or in package development, import from `httpcache`.
replacements for those in the [httr](http://httr.r-lib.org) package. `GET()` responses are added to the local query cache; `PUT()`, `PATCH()`, `POST()`, and `DELETE()` requests trigger cache invalidation on the associated resources. For APIs where a `POST` requests is used to send a command that returns content and doesn't modify state (and hence is semantically more of a `GET`), you can use `cachedPOST()`, which writes to the cache and doesn't invalidate.

To take advantage of these cache-aware functions, all you need to do is load `httpcache` instead of `httr`, or in package development, import from `httpcache`.

```{r}
library(httpcache)
@@ -50,7 +55,8 @@ Notice how the first request results in an "HTTP GET" and a "CACHE SET", while t

### Log analysis

You can also pass a file name to `startLog`. This makes it easier to read the log output back in as a `data.frame` and analyze it quantitatively. We'll do an example of that below.
You can also pass a file name to `startLog`. This makes it easier to read the log output back in as a `data.frame` and analyze it quantitatively.
<!-- We'll do an example of that below. -->

### Custom logging

@@ -66,11 +72,17 @@ regular expression matching to invalidate cache. `dropCache()` is a
convenience wrapper around `dropPattern` that invalidates cache for
any resources that start with the given URL.

Depending on the API with which you're communicating, you may not need to use those cache-invalidation functions directly, or you may need them only infrequently. `httpcache` was designed with [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) APIs in mind, particularly those that expose resources that contain collections of entities that can be created, replaced, updated, and deleted with POST, PUT, PATCH, and DELETE, respectively. Consequently, these four HTTP verb functions are built with default cache invalidation actions: `POST` invalidates cache only for the request URL (`dropOnly`), for the case where POST creates a new entity appearing as a subresource. For example, if `GET http://api.example/projects/` returns a catalog of project entities, and POST to `http://api.example/projects/` creates a resource at `http://api.example/projects/new_id/`, we need to bust cache for the project catalog on POST, but our cached responses for resources such as `http://api.example/projects/old_id/` should still be valid. The other three functions, `PUT`, `PATCH`, and `DELETE`, by default drop cache for the request URL and everything "below" it (`dropCache`). Continuing with the example, if we modify `http://api.example/projects/new_id/`, we should invalidate cache for that resource and for other resources appearing as subresources of it, such as `http://api.example/projects/new_id/users/`.
Depending on the API with which you're communicating, you may not need to use those cache-invalidation functions directly, or you may need them only infrequently. `httpcache` was designed with [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) APIs in mind, particularly those that expose resources that contain collections of entities that can be created, replaced, updated, and deleted ("[CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete)") with POST, PUT, PATCH, and DELETE, respectively. Consequently, these four HTTP verb functions are built with default cache invalidation actions: `POST` invalidates cache only for the request URL (`dropOnly`), for the case where POST creates a new entity appearing as a subresource; while `PUT`, `PATCH`, and `DELETE` drop cache for the request URL and everything "below" it (`dropCache`).

For example, if `GET http://api.example/projects/` returns a catalog of project entities, and POST to `http://api.example/projects/` creates a resource at `http://api.example/projects/new_id/`, we need to bust cache for the project catalog on POST, but our cached responses for resources such as `http://api.example/projects/old_id/` should still be valid. But, if we modify `http://api.example/projects/new_id/`, we should invalidate cache for that resource and for other resources appearing as subresources of it, such as `http://api.example/projects/new_id/users/`.

These verb functions (`POST`, `PUT`, `PATCH`, and `DELETE`) all take a `drop` argument, which defaults as described above. To override them, you can specify a different call other than `dropCache(url)` or `dropOnly(url)`, or you can pass `drop = NULL` and call the cache-invalidation functions directly. Depending on your API and your usage of it, however, `httpcache`'s cache management may just work for you with no additional effort.
These verb functions in `httpcache` (`POST()`, `PUT()`, `PATCH()`, and `DELETE()`) all take a `drop` argument, which defaults as described above. To override them, you can specify a different call other than `dropCache(url)` or `dropOnly(url)`, or you can pass `drop = NULL` and call the cache-invalidation functions directly outside of the request functions. Depending on your API and your usage of it, however, `httpcache`'s cache management may just work for you with no additional effort.

<!--
## Caching across sessions

The query cache you build up in one R session doesn't have to end with it. Use `saveCache()` to write out the contents of your cache to a `.rds` file. Restore it later with `loadCache()`.

<!--
## Example
For a more complete example of the caching, logging, and invalidation features, we'll use a mock HTTP interface from the `httptest` package, which allows demonstration of the features of `httpcache` without requiring a network connection. We'll make a series of requests, both reads and writes, and we'll capture the action with the logging tools.

0 comments on commit a534d3e

Please sign in to comment.
You can’t perform that action at this time.