gdp / doc / developer / gdp-rest-interface.html @ master
History | View | Annotate | Download (22.7 KB)
| 1 |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|---|---|
| 2 |
<html>
|
| 3 |
<head>
|
| 4 |
<meta content="text/html; charset=UTF-8" http-equiv="content-type"> |
| 5 |
<title>GDP REST Interface</title> |
| 6 |
<meta content="Eric Allman" name="author"> |
| 7 |
</head>
|
| 8 |
<body>
|
| 9 |
<h1>RESTful Interface for the Global Data Plane</h1> |
| 10 |
Eric Allman, U.C. Berkeley Swarm Lab<br><br>Revision Notes:<br> |
| 11 |
Draft 8 2017-06-02, rpratt@berkeley.edu: GDP & GCL scope separation, API revisions.<br> |
| 12 |
<p>This document describes the RESTful interface to the Global Data Plane
|
| 13 |
(GDP). Note that this is not part of the GDP itself, since that layer |
| 14 |
treats all records as opaque. This level adds simple key-value structure |
| 15 |
to the data for the convenience of users, and in some cases assumes the |
| 16 |
data is valid JSON text.</p>
|
| 17 |
<h2>1 Introduction</h2> |
| 18 |
<p>This interface is a true RESTful interface, that is, it uses
|
| 19 |
GET/POST/PUT/DELETE instead of overloading everything into |
| 20 |
GET. This implies that requests cannot be submitted using only |
| 21 |
an off the shelf web browser because browsers will only use POST |
| 22 |
methods in response to an HTML form.</p>
|
| 23 |
<p>The data representation chosen is JSON, which is easier to build and
|
| 24 |
parse than XML. <i>[[This should be expanded to include XML as |
| 25 |
specified by the Accept header.]]</i><br> |
| 26 |
</p>
|
| 27 |
<p>All RESTful calls have the prefix "<code>/gdp/v1</code>" to allow |
| 28 |
overloading with other services and to allow multiple versions of the |
| 29 |
protocol to run simultaneously on one node.</p>
|
| 30 |
<p>Objects in the dataplane are called GDP Channel-Logs (GCLs), representing
|
| 31 |
their dual nature as both a communication channel and a storage log. GCLs |
| 32 |
are named with 256-bit values encoded in Base64url notation or as a |
| 33 |
user-meaningful text string, possibly including slashes, which is hashed |
| 34 |
using SHA-256 to produce an internal value.</p>
|
| 35 |
<h2>2 Security</h2> |
| 36 |
<p>Everything stored in the GDP is supposed to be encrypted; however, this
|
| 37 |
interface does not enforce this policy and treats all GDP data as though |
| 38 |
it were encoded in JSON; in particular, in some cases it may be |
| 39 |
encapsulated inside another JSON object. Data returned in response to a |
| 40 |
status request (e.g., for the number of records available) is always |
| 41 |
returned unencrypted as a JSON object.<br>
|
| 42 |
</p>
|
| 43 |
<p><i>A way around this assumption of JSON data content is to return all |
| 44 |
data as base64-encoded strings. However, this puts more work on
|
| 45 |
the client.</i><br> |
| 46 |
</p>
|
| 47 |
<p>Although the data portion of the GDP transaction may be
|
| 48 |
encrypted, an HTTP request/response exchange is not, so it is |
| 49 |
highly recommended that clients authenticate and communicate |
| 50 |
with a RESTful server using HTTPS only. Depending on |
| 51 |
writer-platform capabilities, basic or htdigest client |
| 52 |
authentication within an encrypted session may be useful to gate |
| 53 |
resource consumption and log access within an organization's |
| 54 |
larger security perimeter.</p>
|
| 55 |
<h2>3 Individual Operations</h2> |
| 56 |
<p>In general all GET calls must include "Accept: application/json". <i>Is |
| 57 |
this true?</i><br> |
| 58 |
</p>
|
| 59 |
<p>The symbol <gcl_name> can be either a 43-character base64-encoded |
| 60 |
value or a string composed of characters legal in the path portion of a |
| 61 |
URL (including slashes), either of which is converted to a 256-bit |
| 62 |
location-independent GCL name.<br>
|
| 63 |
</p>
|
| 64 |
<p>The symbol <gcl_id> refers only to the base64-encoded name of a |
| 65 |
GCL.<br>
|
| 66 |
</p>
|
| 67 |
<p>In all cases, timestamps are in ISO 8601 format (<i>YYYY</i>-<i>MM</i>-<i>DD</i>T<i>HH</i>:<i>MM</i>:<i>SS</i>.<i>SSSSSSSSS</i>Z, |
| 68 |
|
| 69 |
|
| 70 |
including nanoseconds, and in UTC) possibly followed by a slash ("/") and
|
| 71 |
a time accuracy in seconds; for example |
| 72 |
"2014-11-22T13:03:09.395023619/3.5" (you can read the slash as |
| 73 |
"±"). Record numbers may be as large as 2<sup>63</sup> |
| 74 |
– 1 (18,446,744,073,709,551,615). </p> |
| 75 |
<h3>Standard GCLs</h3> |
| 76 |
<hr size="2" width="100%"> |
| 77 |
<h4>Name</h4> |
| 78 |
GET /gdp/v1/gcl — list all known GCLs <em>[</em><em><em>NOT |
| 79 |
IMPLEMENTED</em>; see Notes]</em><br> |
| 80 |
<h4>Request Body</h4> |
| 81 |
none<br>
|
| 82 |
<h4>Response</h4> |
| 83 |
<p>200 OK<br> |
| 84 |
</p>
|
| 85 |
<pre> Content-Type: application/json; type=gdp/gcllist
|
| 86 |
<br> [
|
| 87 |
<gcl_id>, |
| 88 |
...<br> ]</pre> |
| 89 |
<p>401 Unauthorized<br> |
| 90 |
</p>
|
| 91 |
<h4>Description</h4> |
| 92 |
<p>Returns a list of GCL names encoded as base64 strings.<br> |
| 93 |
</p>
|
| 94 |
<p><i>[[Should include some way of limiting the number of values, e.g., |
| 95 |
"?start=<#>&max=<#>", since this could be a very large |
| 96 |
list. It would probably be more useful if we could include some
|
| 97 |
query, e.g., only return GCLs where the metadata matches some pattern, |
| 98 |
but that would require a change in the GDP protocol itself.]]</i></p><h4>Notes</h4> |
| 99 |
<p>Not implemented at this time, and is unlikely to be implemented in this form in the future. This requires display of the global state of the GDP, which is likely to be immense. A possible alternative implementation would take a query that would be passed to a directory service. |
| 100 |
Returns 405 Method Not Allowed.<br>
|
| 101 |
</p>
|
| 102 |
<hr size="2" width="100%"> |
| 103 |
<h4>Name</h4> |
| 104 |
GET /gdp/v1/gcl/<gcl_name> — list information known about |
| 105 |
specified GCL <em>[NOT IMPLEMENTED at this time]</em><br> |
| 106 |
<h4>Request Data</h4> |
| 107 |
none<br>
|
| 108 |
<h4>Response Data</h4> |
| 109 |
<p>200 OK<br> |
| 110 |
</p>
|
| 111 |
<pre> Content-Type: application/json; type=gdp/gcldesc
|
| 112 |
<br> {
|
| 113 |
"gcl_id": <gcl_id>,<br> "nrecs": <integer>,<br> ... |
| 114 |
}</pre>
|
| 115 |
<p>The gcl_id will be the internal name of the GCL.<br> |
| 116 |
</p>
|
| 117 |
<p>401 Unauthorized</p> |
| 118 |
<p>404 Not Found<br> |
| 119 |
</p>
|
| 120 |
<h4>Description</h4> |
| 121 |
<p>Returns information about the created GCL encoded as a JSON object. |
| 122 |
The information should at a minimum include the canonical name of the GCL |
| 123 |
and the number of records. When GCL metadata is present it should be
|
| 124 |
returned as well.</p>
|
| 125 |
<p> </p> |
| 126 |
<hr size="2" width="100%"> |
| 127 |
<h4>Name</h4> |
| 128 |
<a id="POST-GCL">POST</a> /gdp/v1/gcl — Create a new GCL with a random name <br> |
| 129 |
<h4>Request Data</h4> |
| 130 |
<p>
|
| 131 |
<pre> Content-Type: application/json;
|
| 132 |
<br> {
|
| 133 |
"external-name": null; |
| 134 |
<i><u>, optional gcl-create parameters</u></i> |
| 135 |
}</pre>
|
| 136 |
<p>The <i><u>optional gcl-create parameters</u></i> are supplied |
| 137 |
as zero or more comma delimited JSON lines. For example: |
| 138 |
</p>
|
| 139 |
<pre> Content-Type: application/json;
|
| 140 |
<br> {
|
| 141 |
"external-name": null, |
| 142 |
"-C": "creator_name@berkeley.edu" |
| 143 |
}</pre>
|
| 144 |
<p>RESTful server supported parameter keys are "-C", "-h", "-k",
|
| 145 |
"-b", "-c", and "-s", and should be paired with a parameter value |
| 146 |
which is valid for the selected parameter key. Consult the |
| 147 |
gcl-create documentation or man page for detailed parameter |
| 148 |
help. Metadata may be optionally specified, using the |
| 149 |
RESTful-unique "META" key, paired with a value which is a JSON |
| 150 |
array of one or more comma separated |
| 151 |
"<metadataname>=<metadata>" strings as array elements. |
| 152 |
</p>
|
| 153 |
</p>
|
| 154 |
<h4>Response Data</h4> |
| 155 |
<p> 201 Created<br> |
| 156 |
</p>
|
| 157 |
<pre> Content-Type: application/json;
|
| 158 |
<br> {
|
| 159 |
"gcl_name": <gcl_id>,<br> "gdplogd_name": <gdplogd_name> |
| 160 |
}</pre>
|
| 161 |
<p>400 Bad Request<br> |
| 162 |
</p>
|
| 163 |
<pre> Content-Type: application/json;
|
| 164 |
<br> {
|
| 165 |
"detail": <detail> |
| 166 |
}</pre>
|
| 167 |
<p>409 Conflict<br> |
| 168 |
</p>
|
| 169 |
<pre> Content-Type: application/json;
|
| 170 |
<br> {
|
| 171 |
"detail": "generated-name conflict on gdplogd server" |
| 172 |
}</pre>
|
| 173 |
<p>500 Internal Server Error<br> |
| 174 |
</p>
|
| 175 |
<pre> Content-Type: application/json;
|
| 176 |
<br> {
|
| 177 |
"detail": <detail><br> [, optional diagnostic key/value pairs] |
| 178 |
}</pre>
|
| 179 |
<h4>Description</h4> |
| 180 |
<p>Creates a new GCL under an internally-assigned name and returns the
|
| 181 |
information about that GCL in the same format as that delivered by the |
| 182 |
status query.</p><h4>Notes</h4><p>The plan is that GCLs will be created using a log creation service that will deal with resource allocation. This command is likely to be an interface to that service.<br> |
| 183 |
</p>
|
| 184 |
<hr size="2" width="100%"> |
| 185 |
<h4>Name</h4> |
| 186 |
<a id="PUT-GCL">PUT</a> /gdp/v1/gcl — Create a new GCL with a specified name <br> |
| 187 |
<h4>Request Data</h4> |
| 188 |
<p>
|
| 189 |
<pre> Content-Type: application/json;
|
| 190 |
<br> {
|
| 191 |
"external-name": <user_selected_name> |
| 192 |
<i><u>, optional gcl-create parameters</u></i> |
| 193 |
}</pre>
|
| 194 |
<p>The <i><u>optional gcl-create parameters</u></i> are supplied |
| 195 |
as zero or more comma delimited JSON lines. For example: |
| 196 |
</p>
|
| 197 |
<pre> Content-Type: application/json;
|
| 198 |
<br> {
|
| 199 |
"external-name": "edu.berkeley.eecs.swarmlab.test.log00", |
| 200 |
"-C": "creator_name@berkeley.edu" |
| 201 |
}</pre>
|
| 202 |
<p>RESTful server supported parameter keys are "-C", "-h", "-k",
|
| 203 |
"-b", "-c", and "-s", and should be paired with a parameter value |
| 204 |
which is valid for the selected parameter key. Consult the |
| 205 |
gcl-create documentation or man page for detailed parameter |
| 206 |
help. Metadata may be optionally specified, using the |
| 207 |
RESTful-unique "META" key, paired with a value which is a JSON |
| 208 |
array of one or more comma separated |
| 209 |
"<metadataname>=<metadata>" strings as array elements. |
| 210 |
</p>
|
| 211 |
</p>
|
| 212 |
<h4>Response Data</h4> |
| 213 |
<p> 201 Created<br> |
| 214 |
</p>
|
| 215 |
</p>
|
| 216 |
<pre> Content-Type: application/json;
|
| 217 |
<br> {
|
| 218 |
"gcl_name": <gcl_id>,<br> "gdplogd_name": <gdplogd_name> |
| 219 |
}</pre>
|
| 220 |
<p>400 Bad Request<br> |
| 221 |
</p>
|
| 222 |
<pre> Content-Type: application/json;
|
| 223 |
<br> {
|
| 224 |
"detail": <detail> |
| 225 |
}</pre>
|
| 226 |
<p>409 Conflict<br> |
| 227 |
</p>
|
| 228 |
<pre> Content-Type: application/json;
|
| 229 |
<br> {
|
| 230 |
"detail": "external-name already exists on gdplogd server" |
| 231 |
}</pre>
|
| 232 |
<p>500 Internal Server Error<br> |
| 233 |
</p>
|
| 234 |
<pre> Content-Type: application/json;
|
| 235 |
<br> {
|
| 236 |
"detail": <detail><br> [, optional diagnostic key/value pairs] |
| 237 |
}</pre>
|
| 238 |
<h4>Description</h4> |
| 239 |
<p>Creates a new GCL under a user-assigned name and returns the
|
| 240 |
information about the creation of that GCL, or reports a |
| 241 |
conflict if the name already exists.</p>
|
| 242 |
<hr size="2" width="100%"> |
| 243 |
<h4>Name</h4> |
| 244 |
DELETE /gdp/v1/gcl — delete a GCL <em>[NOT IMPLEMENTED; see Notes]</em><br> |
| 245 |
<h4>Request Data</h4> |
| 246 |
<p>
|
| 247 |
<pre> Content-Type: application/json;
|
| 248 |
<br> {
|
| 249 |
"external-name": <user_selected_name> |
| 250 |
}</pre>
|
| 251 |
</p>
|
| 252 |
<h4>Response</h4> |
| 253 |
<p>204 No Content</p> |
| 254 |
<p>401 Unauthorized</p> |
| 255 |
<p>404 Not Found<br> |
| 256 |
</p>
|
| 257 |
<h4>Description</h4><h4>Notes</h4><p>Currently the GDP does not support log deletion. Until it does this will not be implemented.</p> |
| 258 |
<p><br> |
| 259 |
</p>
|
| 260 |
<hr size="2" width="100%"> |
| 261 |
<h4>Name</h4> |
| 262 |
<a id="POST-REC">POST</a> /gdp/v1/gcl/<gcl_name> — add a record to specified GCL<br> |
| 263 |
<h4>Request Data</h4> |
| 264 |
(Opaque data to be appended, but recommended to use JSON)<br>
|
| 265 |
<h4>Response Data</h4> |
| 266 |
<p>201 Created<br> |
| 267 |
</p>
|
| 268 |
<pre> Content-Type: application/json; type=gdp/response<br><br> { |
| 269 |
"gcl_id": <gcl_id>, |
| 270 |
"recno": <integer>,<br> "timestamp": <commit timestamp><br> ... |
| 271 |
}</pre>
|
| 272 |
<p>401 Unauthorized<br> |
| 273 |
</p>
|
| 274 |
<p>404 Not Found<br> |
| 275 |
</p>
|
| 276 |
<h4>Description</h4> |
| 277 |
<p>Adds a record to the named GCL. The information returned shows the |
| 278 |
GDP-assigned metadata associated with the new record.<br>
|
| 279 |
</p>
|
| 280 |
<p> </p> |
| 281 |
<hr size="2" width="100%"> |
| 282 |
<h4>Name</h4> |
| 283 |
<a id="GET-REC">GET</a> /gdp/v1/gcl/<gcl_name>?recno=<#> — return a specified |
| 284 |
record<br>
|
| 285 |
<h4>Request Data</h4> |
| 286 |
none<br>
|
| 287 |
<h4>Response Data</h4> |
| 288 |
<p>200 OK<br> |
| 289 |
</p>
|
| 290 |
<pre> Content-Type: <as specified as metadata during GCL creation> |
| 291 |
GDP-Record-Number: <recno><br> GDP-Commit-Timestamp: <timestamp><br><br> <opaque data as written by POST></pre> |
| 292 |
<p> </p> |
| 293 |
<p>404 Not Found<br> |
| 294 |
</p>
|
| 295 |
<h4>Description</h4> |
| 296 |
<p>Returns the contents of the record indicated by <i>recno</i>. As a |
| 297 |
special case, if recno is the text "last" it returns the last (most |
| 298 |
recently written) record.<br>
|
| 299 |
</p>
|
| 300 |
<p>Note that the metadata is included in the response header, not in the
|
| 301 |
data itself, in order to maintain the opacity of that data. <i>Question:
|
| 302 |
should we move the metadata into the header for other commands as well |
| 303 |
to maintain symmetry?</i><br> |
| 304 |
</p>
|
| 305 |
<p>This call is not orthogonal to the others because it does not assume that
|
| 306 |
the data is application/json.<br>
|
| 307 |
</p>
|
| 308 |
<hr size="2" width="100%"> |
| 309 |
<p> </p> |
| 310 |
<h4>Name</h4> |
| 311 |
GET /gdp/v1/gcl/<gcl_name>?recno=<#>&nrecs=<#> — |
| 312 |
get a series of records<br>
|
| 313 |
<h4>Request Data</h4> |
| 314 |
none<br>
|
| 315 |
<h4>Response</h4> |
| 316 |
200 OK<br>
|
| 317 |
<pre> [<br> {<br> "recno": <integer>,<br> "timestamp": <timestamp>,<br> "value": <record value><br> },<br> ...<br> ]</pre> |
| 318 |
404 Not Found<br>
|
| 319 |
<h4>Description</h4> |
| 320 |
<p>Returns a sequence of up to <i>nrecs</i> records starting from <i>recno</i> |
| 321 |
encoded as an array of JSON objects. If <i>nrecs</i> is zero, all |
| 322 |
data from <i>recno</i> to the end is returned. The <i>recno</i> |
| 323 |
parameter is optional and defaults to 1.</p>
|
| 324 |
<p>The <var>nrecs</var> parameter is not implemented at this time.<br> |
| 325 |
</p>
|
| 326 |
<hr size="2" width="100%"> |
| 327 |
<h4>Name</h4> |
| 328 |
GET |
| 329 |
/gdp/v1/gcl/gcl_id?recno=<#>&nrecs=<#>&timeout=<seconds> |
| 330 |
|
| 331 |
|
| 332 |
|
| 333 |
|
| 334 |
— monitor a GCL<br> |
| 335 |
<h4>Request Data</h4> |
| 336 |
none<br>
|
| 337 |
<h4>Response Data</h4> |
| 338 |
<p>200 OK<br> |
| 339 |
</p>
|
| 340 |
<p>401 Unauthorized<br> |
| 341 |
</p>
|
| 342 |
<p>404 Not Found<br> |
| 343 |
</p>
|
| 344 |
<p>408 Request Timeout<br> |
| 345 |
</p>
|
| 346 |
<h4>Description</h4> |
| 347 |
<p>If the indicated GCL does not exist, the GET returns immediately with a
|
| 348 |
404 error code. Otherwise, if the indicated record number exists, the |
| 349 |
result is exactly the same as the previous case. If the indicated record |
| 350 |
number does not exist, this call waits for up to the indicated timeout for |
| 351 |
that record to appear; if it does, the record is returned in the usual |
| 352 |
way, otherwise it returns with a 408 Request Timeout response. If the |
| 353 |
starting record number is not specified, it starts from the beginning.</p><h4>Notes</h4> |
| 354 |
<p>The <var>nrecs</var> and <var>timeout</var> parameters are not |
| 355 |
implemented at this time.</p>
|
| 356 |
<p><i>[[Perhaps this should not take recno and nrecs, and just return the |
| 357 |
next record that appears at the GCL.]]</i><br> |
| 358 |
</p>
|
| 359 |
<p><i>[[There is some debate about whether this is the correct interface |
| 360 |
rather than falling back to a non-REST interface (such as WebSockets) |
| 361 |
for subscriptions. HTTP (and hence REST) isn’t designed to handle
|
| 362 |
spontaneous server to client messages.</i><i>]]</i><br> |
| 363 |
</p>
|
| 364 |
<hr size="2" width="100%"> |
| 365 |
<h4>Name</h4> |
| 366 |
GET /gdp/v1/post/gcl/<gcl_name>?<arguments> — add data to |
| 367 |
a GCL (<i><b>not REST compliant</b></i>)<br> |
| 368 |
<h4>Description</h4> |
| 369 |
<p>To be determined. Probably will create a JSON object including the |
| 370 |
specified arguments and append that to the GCL, unencrypted of course.<br>
|
| 371 |
</p>
|
| 372 |
<p> </p> |
| 373 |
<hr size="2" width="100%"> |
| 374 |
<h3>Key-Value Store</h3> |
| 375 |
<p>The key-value store is implemented as a single GCL that must be formatted
|
| 376 |
as unencrypted JSON data structured as a series of JSON objects. The
|
| 377 |
"keys" are the field names in that top level object. When adding
|
| 378 |
data to the KV store an arbitrary number of values may be sent in any one |
| 379 |
record. When retrieving data the key name is specified and the most
|
| 380 |
recent value corresponding to that key is returned.</p>
|
| 381 |
<p>The GCL used to implement is named "<code>swarm.rest.kvstore.gcl</code>". |
| 382 |
It may be overridden with the "<code>swarm.rest.kvstore.gclname</code>" |
| 383 |
administrative runtime parameter.</p>
|
| 384 |
<p>Note that another way of implementing a KV store is to have an arbitrary
|
| 385 |
GCL, the name of which represents the key, and just get the last (most |
| 386 |
recent) value to get the current value for that key. This trades off
|
| 387 |
a potentially large key space for efficiency and lack of clutter.</p>
|
| 388 |
<hr size="2" width="100%"> |
| 389 |
<h4>Name</h4> |
| 390 |
POST /gdp/v1/kv — add data to key-value store<br> |
| 391 |
<h4>Description</h4> |
| 392 |
<p>There is a single key-value store. All data must be formatted as |
| 393 |
JSON objects. POST adds all of the names inside the content to the
|
| 394 |
KV store. For example a POST with the contents { "a": 1, "b": 2 }
|
| 395 |
adds two values to the store. A subsequent POST with contents { "a":
|
| 396 |
3, "c": 4 } updates the value of a, adds a new value c, and leaves b |
| 397 |
unchanged.</p>
|
| 398 |
<hr size="2" width="100%"> |
| 399 |
<h4>Name</h4> |
| 400 |
<p>GET /gdp/v1/kv/<key><br> |
| 401 |
</p>
|
| 402 |
<h4>Description</h4> |
| 403 |
<p>Returns the value of <key> in JSON notation.<br> |
| 404 |
</p>
|
| 405 |
<hr size="2" width="100%"> |
| 406 |
<p><br> |
| 407 |
</p>
|
| 408 |
<a id="Summary"><h2> 4 Summary</h2></a> |
| 409 |
<p>This is just a quick recap of the material presented above. All |
| 410 |
URLs begin with "<code>/gdp/v1/</code>".<br> |
| 411 |
</p>
|
| 412 |
<table border="1" cellpadding="2" cellspacing="2" width="100%"> |
| 413 |
<tbody>
|
| 414 |
<tr>
|
| 415 |
<td valign="top"><H4>Scope</H4> |
| 416 |
</td>
|
| 417 |
<td valign="top"><H3>Method</H3> |
| 418 |
</td>
|
| 419 |
<td valign="top"><H3>URI Path</H3> |
| 420 |
</td>
|
| 421 |
<td valign="top"><H3>Description</H3> |
| 422 |
</td>
|
| 423 |
</tr>
|
| 424 |
<tr>
|
| 425 |
<td valign="top">GDP<br> |
| 426 |
</td>
|
| 427 |
<td valign="top">GET<br> |
| 428 |
</td>
|
| 429 |
<td valign="top">gcl<br> |
| 430 |
</td>
|
| 431 |
<td valign="top"><span style="text-decoration: line-through;">Lists existing GCLs</span> <br>[405 Method Not Allowed]<br> |
| 432 |
</td>
|
| 433 |
</tr>
|
| 434 |
<tr>
|
| 435 |
<td valign="top">GDP<br> |
| 436 |
</td>
|
| 437 |
<td valign="top">POST<br> |
| 438 |
</td>
|
| 439 |
<td valign="top">gcl<br> |
| 440 |
</td>
|
| 441 |
<td valign="top">Create new GCL with random name<br> |
| 442 |
</td>
|
| 443 |
</tr>
|
| 444 |
<tr>
|
| 445 |
<td valign="top">GDP<br> |
| 446 |
</td>
|
| 447 |
<td valign="top">PUT<br> |
| 448 |
</td>
|
| 449 |
<td valign="top">gcl<br> |
| 450 |
</td>
|
| 451 |
<td valign="top">Create new GCL with specified name<br> |
| 452 |
</td>
|
| 453 |
</tr>
|
| 454 |
<tr>
|
| 455 |
<td valign="top">GDP<br> |
| 456 |
</td>
|
| 457 |
<td valign="top">DELETE<br> |
| 458 |
</td>
|
| 459 |
<td valign="top">gcl<br> |
| 460 |
</td>
|
| 461 |
<td valign="top"><span style="text-decoration: line-through;">Delete GCL</span><br>[405 Method Not Allowed]<br> |
| 462 |
</td>
|
| 463 |
</tr>
|
| 464 |
<tr>
|
| 465 |
<td valign="top">GCL<br> |
| 466 |
</td>
|
| 467 |
<td valign="top">GET<br> |
| 468 |
</td>
|
| 469 |
<td valign="top">gcl/<id><br> |
| 470 |
</td>
|
| 471 |
<td valign="top"><span style="text-decoration: line-through;">GCL <id> read metadata</span><br>[405 Method Not Allowed]<br> |
| 472 |
</td>
|
| 473 |
</tr>
|
| 474 |
<tr>
|
| 475 |
<td valign="top">GCL<br> |
| 476 |
</td>
|
| 477 |
<td valign="top">POST</td> |
| 478 |
<td valign="top">gcl/<id><br> |
| 479 |
</td>
|
| 480 |
<td valign="top">GCL <id> append record<br> |
| 481 |
</td>
|
| 482 |
</tr>
|
| 483 |
<tr>
|
| 484 |
<td valign="top">GCL<br> |
| 485 |
</td>
|
| 486 |
<td valign="top">PUT<br> |
| 487 |
</td>
|
| 488 |
<td valign="top">gcl/<id>?recno=<#><br> |
| 489 |
</td>
|
| 490 |
<td valign="top"><span style="text-decoration: line-through;">GCL <id> append record at recno or report conflict</span> <br>[405 Method Not Allowed]<br> |
| 491 |
</td>
|
| 492 |
</tr>
|
| 493 |
<tr>
|
| 494 |
<td valign="top">GCL<br> |
| 495 |
</td>
|
| 496 |
<td valign="top">DELETE<br> |
| 497 |
</td>
|
| 498 |
<td valign="top">gcl/<id><br> |
| 499 |
</td>
|
| 500 |
<td valign="top"><span style="text-decoration: line-through;">GCL <id> delete record</span><br>Deprecated: GCL is append-only by design<br> |
| 501 |
</td>
|
| 502 |
</tr>
|
| 503 |
<tr>
|
| 504 |
<td valign="top">GCL<br> |
| 505 |
</td>
|
| 506 |
<td valign="top">GET<br> |
| 507 |
</td>
|
| 508 |
<td valign="top">gcl/<id>?recno=<#><br> |
| 509 |
</td>
|
| 510 |
<td valign="top">GCL <id> read record at recno<br>(returns raw data)<br> |
| 511 |
</td>
|
| 512 |
</tr>
|
| 513 |
<tr>
|
| 514 |
<td valign="top">GCL<br> |
| 515 |
</td>
|
| 516 |
<td valign="top">GET<br> |
| 517 |
</td>
|
| 518 |
<td valign="top">gcl/<id>?recno=<#>&nrecs=<#><br> |
| 519 |
</td>
|
| 520 |
<td valign="top"><span style="text-decoration: line-through;">GCL <id> read nrecs records starting from recno</span><br>Deprecated: violates REST standard (nrecs value is not limited). Use websocket API instead.<br> |
| 521 |
</td>
|
| 522 |
</tr>
|
| 523 |
<tr>
|
| 524 |
<td valign="top">GCL<br> |
| 525 |
</td>
|
| 526 |
<td valign="top">GET<br> |
| 527 |
</td>
|
| 528 |
<td valign="top">gcl/<id>?timeout=<#><br> |
| 529 |
</td>
|
| 530 |
<td valign="top"><span style="text-decoration: line-through;">Wait for new data to appear on GCL</span><br>Deprecated: violates REST standard (subscription). Use websocket API instead.<br> |
| 531 |
</td>
|
| 532 |
</tr>
|
| 533 |
<tr>
|
| 534 |
<td valign="top">GCL<br> |
| 535 |
</td>
|
| 536 |
<td valign="top">GET<br> |
| 537 |
</td>
|
| 538 |
<td valign="top">put/gcl/<id>?<arguments><br> |
| 539 |
</td>
|
| 540 |
<td valign="top"><span style="text-decoration: line-through;">Add JSON record to GCL <id></span><br>Deprecated: violates REST standard (arguments are not limited).<br> |
| 541 |
</td>
|
| 542 |
</tr>
|
| 543 |
<tr>
|
| 544 |
<td valign="top">RESTful Server<br> |
| 545 |
</td>
|
| 546 |
<td valign="top">POST<br> |
| 547 |
</td>
|
| 548 |
<td valign="top">kv<br> |
| 549 |
</td>
|
| 550 |
<td valign="top">Add JSON information to key-value store<br> |
| 551 |
</td>
|
| 552 |
</tr>
|
| 553 |
<tr>
|
| 554 |
<td valign="top">RESTful Server<br> |
| 555 |
</td>
|
| 556 |
<td valign="top">GET<br> |
| 557 |
</td>
|
| 558 |
<td valign="top">kv/<key><br> |
| 559 |
</td>
|
| 560 |
<td valign="top">Return JSON information associated with <key> |
| 561 |
in the key-value store<br>
|
| 562 |
</td>
|
| 563 |
</tr>
|
| 564 |
</tbody>
|
| 565 |
</table>
|
| 566 |
<p><br> |
| 567 |
</p>
|
| 568 |
<h2>4 Unresolved Issues</h2> |
| 569 |
<p>Do subscriptions wait until all data is ready to return, or does it
|
| 570 |
return immediately as soon as any data appears?</p>
|
| 571 |
<p>How are signatures on POST methods handled?</p></p> |
| 572 |
<h2> </h2> |
| 573 |
</body></html> |