RestUri-class | R Documentation |
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
.
container(x)
: Gets a RestContainer
object for treating x
as a list-like container.
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
.
Michael Lawrence
apache <- RestUri("http://wiki.apache.org") read(apache$solr)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.