1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
\name{RestUri-class}
\docType{class}
\alias{class:RestUri}
\alias{RestUri-class}
% CRUD:
\alias{create}
\alias{create,RestUri-method}
\alias{read}
\alias{read,RestUri-method}
\alias{update}
\alias{update,RestUri-method}
\alias{delete}
\alias{delete,RestUri-method}
\alias{create,character-method}
\alias{read,character-method}
\alias{update,character-method}
\alias{delete,character-method}
% Construction:
\alias{RestUri}
\alias{$,RestUri-method}
\alias{[[,RestUri-method}
\alias{$<-,RestUri-method}
\alias{[[<-,RestUri-method}
\alias{[,RestUri-method}
% Container:
\alias{container}
\alias{container,RestUri-method}
\alias{container<-}
\alias{container<-,RestUri-method}
% Utilities
\alias{purgeCache}
\alias{purgeCache,RestUri-method}
\alias{embedCredentials}
% Authentication:
\alias{authenticate}
\alias{authenticate,RestUri-method}
\alias{credentials,RestUri-method}
% Show:
\alias{show,RestUri-method}
\title{RestUri}
\description{
The \code{RestUri} object represents a resource accessible via a
RESTful interface. It extends \code{character} with a protocol, used
for accessing the data, as well as a cache. R objects are converted
to/from external media via the \code{\linkS4class{Media}} framework.
}
\section{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 \code{RestUri} and \code{character} (taken to be a
URI), described below.
\itemize{
\item{
\code{create(x, value, ..., returnResponse=FALSE)}: Creates a
resource at \code{x} by converting \code{value} to a supported
media type. The \dots become query parameters on \code{x}. If
\code{returnResponse} is \code{TRUE}, convert and return any
response sent from the endpoint. By default, \code{x} is returned,
to support chaining. This corresponds to an HTTP \code{POST}.
}
\item{
\code{read(x, ...)}: Reads the resource at \code{x}, coerces it to
an R object, and returns the object. The \dots become query
parameters on \code{x}. This corresponds to an HTTP \code{GET}.
}
\item{
\code{update(object, value, ...)}: Updates the resource at \code{x} by
converting \code{value} to a supported media type. The \dots
become query parameters on \code{x}. This corresponds to an HTTP
\code{PUT}.
}
\item{
\code{delete(x, ...)}: Deletes the resource at \code{x}. This
corresponds to an HTTP \code{DELETE}.
}
}
}
\section{Constructor}{
\itemize{
\item{
\code{RestUri(base.uri, protocol = CRUDProtocol(base.uri, ...),
cache = globalRestClientCache(), ...)}: Constructs a
\code{RestUri} object, pointing to \code{base.uri}, a string
representation of the URI. The \code{protocol} (a
\code{\linkS4class{CRUDProtocol}} instance) is automatically
determined from the scheme of the URI. By default, all instances
share the same global \code{cache}, a
\code{\linkS4class{MediaCache}} instance.
}
\item{\code{x$name}: Extends the path of \code{x} by appending
\code{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.
}
\item{\code{x[[i]]}: Extends the path of \code{x} by appending
\code{i}.
}
\item{\code{x[...]}: Named arguments in \code{...} become query
parameters on \code{x}.
}
}
}
\section{Container support}{
\itemize{
\item{
\code{container(x)}: Gets a \code{\linkS4class{RestContainer}}
object for treating \code{x} as a list-like container.
}
}
}
\section{Authentication}{
RestUri currently supports basic HTTP authentication. Call
\code{authenticate(x)} to add credentials to the RestUri
\code{x}. Retrieve the Credentials object with the \code{credentials}
accessor.
Once a set of credentials has been entered, it is recorded for the URI
in \file{$(HOME)/.local/config/restfulr/credentials.yaml}. The path
prefix can be changed via the \env{XDG_CONFIG_DIR} environment
variable, according to the \acronym{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 \pkg{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.
}
\section{Utilities}{
\itemize{
\item{\code{embedCredentials(x)}: Embeds the internal credential
information into the URL itself, for interfacing with other tools,
like \code{utils::download.file}.
}
}
}
\examples{
apache <- RestUri("http://wiki.apache.org")
read(apache$solr)
}
\author{ Michael Lawrence }
\keyword{methods}
\keyword{classes}
|
