RestUri-class {restfulr}

RestUri

Description

The RestUri object represents a resource accessible via a RESTful interface. It extends character with a protocol, used for accessing the data, as well as a cache. R objects are converted to/from external media via the Media framework.

CRUD interface

There are four canonical, abstract types of REST operations: create, read, update, delete (CRUD). The CRUD model was borrowed from traditional databases. The restfulr package maps those four operations to R functions of the same name. The functions are generic, and there are methods for RestUri and character (taken to be a URI), described below.

• create(x, value, ..., returnResponse=FALSE): Creates a resource at x by converting value to a supported media type. The ... become query parameters on x. If returnResponse is TRUE, convert and return any response sent from the endpoint. By default, x is returned, to support chaining. This corresponds to an HTTP POST.

• read(x, ...): Reads the resource at x, coerces it to an R object, and returns the object. The ... become query parameters on x. This corresponds to an HTTP GET.

• update(object, value, ...): Updates the resource at x by converting value to a supported media type. The ... become query parameters on x. This corresponds to an HTTP PUT.

• delete(x, ...): Deletes the resource at x. This corresponds to an HTTP DELETE.

Constructor

• RestUri(base.uri, protocol = CRUDProtocol(base.uri, ...), cache = globalRestClientCache(), ...): Constructs a RestUri object, pointing to base.uri, a string representation of the URI. The protocol (a CRUDProtocol instance) is automatically determined from the scheme of the URI. By default, all instances share the same global cache, a MediaCache instance.

• x$name: Extends the path of x by appending name. This is a convenient way to narrow a URI and is intuitive if one thinks of a tree of resources as a nested list.

• x[[i]]: Extends the path of x by appending i.

• x[...]: Named arguments in ... become query parameters on x.

Container support

• container(x): Gets a RestContainer object for treating x as a list-like container.

Authentication

RestUri currently supports basic HTTP authentication. Call authenticate(x) to add credentials to the RestUri x. Retrieve the Credentials object with the credentials accessor.

Once a set of credentials has been entered, it is recorded for the URI in ‘$(HOME)/.local/config/restfulr/credentials.yaml’. The path prefix can be changed via the XDG_CONFIG_DIR environment variable, according to the XDG standard. The credential cache is checked during authentication, so that a user does not need to reenter credentials for the same URI.

If the getPass package is installed, we use it for password entry. Otherwise, we rely on an implementation that shows the password as it is entered, unless the user is in a terminal, where we can hide input.

Utilities

• embedCredentials(x): Embeds the internal credential information into the URL itself, for interfacing with other tools, like utils::download.file.

Author(s)

Michael Lawrence

Examples

apache <- RestUri("http://wiki.apache.org")
read(apache$solr)