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.
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
.
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
.
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.
embedCredentials(x)
: Embeds the internal credential
information into the URL itself, for interfacing with other tools,
like utils::download.file
.
# NOT RUN {
apache <- RestUri("http://wiki.apache.org")
read(apache$solr)
# }
Run the code above in your browser using DataLab