gdp / doc / developer / gdp-rest-interface.html @ master
History | View | Annotate | Download (22.7 KB)
| 1 | 18188fcc | Eric Allman | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|---|---|---|---|
| 2 | <html>
|
||
| 3 | <head>
|
||
| 4 | 26fa111b | Eric Allman | <meta content="text/html; charset=UTF-8" http-equiv="content-type"> |
| 5 | 18188fcc | Eric Allman | <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 | 04ad7859 | Rick Pratt | 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 | 26fa111b | Eric Allman | <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 | 18188fcc | Eric Allman | <h2>1 Introduction</h2> |
| 18 | <p>This interface is a true RESTful interface, that is, it uses
|
||
| 19 | 04ad7859 | Rick Pratt | 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 | 26fa111b | Eric Allman | <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 | 18188fcc | Eric Allman | </p>
|
| 27 | <p>All RESTful calls have the prefix "<code>/gdp/v1</code>" to allow |
||
| 28 | 26fa111b | Eric Allman | 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 | 18188fcc | Eric Allman | <h2>2 Security</h2> |
| 36 | 26fa111b | Eric Allman | <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 | 04ad7859 | Rick Pratt | <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 | 18188fcc | Eric Allman | <h2>3 Individual Operations</h2> |
| 56 | 26fa111b | Eric Allman | <p>In general all GET calls must include "Accept: application/json". <i>Is |
| 57 | this true?</i><br> |
||
| 58 | 18188fcc | Eric Allman | </p>
|
| 59 | 26fa111b | Eric Allman | <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 | 18188fcc | Eric Allman | </p>
|
| 64 | 26fa111b | Eric Allman | <p>The symbol <gcl_id> refers only to the base64-encoded name of a |
| 65 | GCL.<br>
|
||
| 66 | 18188fcc | Eric Allman | </p>
|
| 67 | 9eeb635c | Eric Allman | <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 | 2b29bb77 | Eric Allman | |
| 70 | 26fa111b | Eric Allman | including nanoseconds, and in UTC) possibly followed by a slash ("/") and
|
| 71 | a time accuracy in seconds; for example |
||
| 72 | 9eeb635c | Eric Allman | "2014-11-22T13:03:09.395023619/3.5" (you can read the slash as |
| 73 | 26fa111b | Eric Allman | "±"). Record numbers may be as large as 2<sup>63</sup> |
| 74 | – 1 (18,446,744,073,709,551,615). </p> |
||
| 75 | a29668f9 | Eric Allman | <h3>Standard GCLs</h3> |
| 76 | 9eeb635c | Eric Allman | <hr size="2" width="100%"> |
| 77 | 18188fcc | Eric Allman | <h4>Name</h4> |
| 78 | 9148e726 | Eric Allman | GET /gdp/v1/gcl — list all known GCLs <em>[</em><em><em>NOT |
| 79 | IMPLEMENTED</em>; see Notes]</em><br> |
||
| 80 | 18188fcc | Eric Allman | <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 | 26fa111b | Eric Allman | ...<br> ]</pre> |
| 89 | 18188fcc | Eric Allman | <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 | 26fa111b | Eric Allman | <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 | 9148e726 | Eric Allman | 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 | 26fa111b | Eric Allman | Returns 405 Method Not Allowed.<br>
|
| 101 | 18188fcc | Eric Allman | </p>
|
| 102 | 9eeb635c | Eric Allman | <hr size="2" width="100%"> |
| 103 | 18188fcc | Eric Allman | <h4>Name</h4> |
| 104 | 26fa111b | Eric Allman | GET /gdp/v1/gcl/<gcl_name> — list information known about |
| 105 | 9148e726 | Eric Allman | specified GCL <em>[NOT IMPLEMENTED at this time]</em><br> |
| 106 | 18188fcc | Eric Allman | <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 | 26fa111b | Eric Allman | <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 | 18188fcc | Eric Allman | <p> </p> |
| 126 | 9eeb635c | Eric Allman | <hr size="2" width="100%"> |
| 127 | 18188fcc | Eric Allman | <h4>Name</h4> |
| 128 | a3aab530 | Rick Pratt | <a id="POST-GCL">POST</a> /gdp/v1/gcl — Create a new GCL with a random name <br> |
| 129 | 18188fcc | Eric Allman | <h4>Request Data</h4> |
| 130 | 04ad7859 | Rick Pratt | <p>
|
| 131 | <pre> Content-Type: application/json;
|
||
| 132 | <br> {
|
||
| 133 | 74bfe519 | Rick Pratt | "external-name": null; |
| 134 | 04ad7859 | Rick Pratt | <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 | 4759a8bc | Rick Pratt | "-b", "-c", and "-s", and should be paired with a parameter value |
| 146 | 04ad7859 | Rick Pratt | 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 | 18188fcc | Eric Allman | <h4>Response Data</h4> |
| 155 | <p> 201 Created<br> |
||
| 156 | </p>
|
||
| 157 | 04ad7859 | Rick Pratt | <pre> Content-Type: application/json;
|
| 158 | 18188fcc | Eric Allman | <br> {
|
| 159 | 04ad7859 | Rick Pratt | "gcl_name": <gcl_id>,<br> "gdplogd_name": <gdplogd_name> |
| 160 | 18188fcc | Eric Allman | }</pre>
|
| 161 | 04ad7859 | Rick Pratt | <p>400 Bad Request<br> |
| 162 | 18188fcc | Eric Allman | </p>
|
| 163 | 04ad7859 | Rick Pratt | <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 | 26fa111b | Eric Allman | <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 | 9148e726 | Eric Allman | 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 | 18188fcc | Eric Allman | </p>
|
| 184 | 9eeb635c | Eric Allman | <hr size="2" width="100%"> |
| 185 | 18188fcc | Eric Allman | <h4>Name</h4> |
| 186 | a3aab530 | Rick Pratt | <a id="PUT-GCL">PUT</a> /gdp/v1/gcl — Create a new GCL with a specified name <br> |
| 187 | 18188fcc | Eric Allman | <h4>Request Data</h4> |
| 188 | 04ad7859 | Rick Pratt | <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 | 4759a8bc | Rick Pratt | "-b", "-c", and "-s", and should be paired with a parameter value |
| 204 | 04ad7859 | Rick Pratt | 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 | 18188fcc | Eric Allman | <h4>Response Data</h4> |
| 213 | <p> 201 Created<br> |
||
| 214 | </p>
|
||
| 215 | 04ad7859 | Rick Pratt | </p>
|
| 216 | <pre> Content-Type: application/json;
|
||
| 217 | 18188fcc | Eric Allman | <br> {
|
| 218 | 04ad7859 | Rick Pratt | "gcl_name": <gcl_id>,<br> "gdplogd_name": <gdplogd_name> |
| 219 | 18188fcc | Eric Allman | }</pre>
|
| 220 | 04ad7859 | Rick Pratt | <p>400 Bad Request<br> |
| 221 | 18188fcc | Eric Allman | </p>
|
| 222 | 04ad7859 | Rick Pratt | <pre> Content-Type: application/json;
|
| 223 | <br> {
|
||
| 224 | "detail": <detail> |
||
| 225 | }</pre>
|
||
| 226 | <p>409 Conflict<br> |
||
| 227 | 18188fcc | Eric Allman | </p>
|
| 228 | 04ad7859 | Rick Pratt | <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 | 18188fcc | Eric Allman | </p>
|
| 234 | 04ad7859 | Rick Pratt | <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 | 9eeb635c | Eric Allman | <hr size="2" width="100%"> |
| 243 | 18188fcc | Eric Allman | <h4>Name</h4> |
| 244 | 04ad7859 | Rick Pratt | DELETE /gdp/v1/gcl — delete a GCL <em>[NOT IMPLEMENTED; see Notes]</em><br> |
| 245 | 18188fcc | Eric Allman | <h4>Request Data</h4> |
| 246 | 04ad7859 | Rick Pratt | <p>
|
| 247 | <pre> Content-Type: application/json;
|
||
| 248 | <br> {
|
||
| 249 | "external-name": <user_selected_name> |
||
| 250 | }</pre>
|
||
| 251 | 18188fcc | Eric Allman | </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 | 9148e726 | Eric Allman | <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 | 18188fcc | Eric Allman | <p><br> |
| 259 | </p>
|
||
| 260 | 9eeb635c | Eric Allman | <hr size="2" width="100%"> |
| 261 | 18188fcc | Eric Allman | <h4>Name</h4> |
| 262 | a3aab530 | Rick Pratt | <a id="POST-REC">POST</a> /gdp/v1/gcl/<gcl_name> — add a record to specified GCL<br> |
| 263 | 18188fcc | Eric Allman | <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 | 26fa111b | Eric Allman | <p>Adds a record to the named GCL. The information returned shows the |
| 278 | GDP-assigned metadata associated with the new record.<br>
|
||
| 279 | 18188fcc | Eric Allman | </p>
|
| 280 | <p> </p> |
||
| 281 | 9eeb635c | Eric Allman | <hr size="2" width="100%"> |
| 282 | 18188fcc | Eric Allman | <h4>Name</h4> |
| 283 | a3aab530 | Rick Pratt | <a id="GET-REC">GET</a> /gdp/v1/gcl/<gcl_name>?recno=<#> — return a specified |
| 284 | 26fa111b | Eric Allman | record<br>
|
| 285 | 18188fcc | Eric Allman | <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 | 26fa111b | Eric Allman | <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 | 18188fcc | Eric Allman | </p>
|
| 300 | 26fa111b | Eric Allman | <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 | 18188fcc | Eric Allman | </p>
|
| 305 | 26fa111b | Eric Allman | <p>This call is not orthogonal to the others because it does not assume that
|
| 306 | the data is application/json.<br>
|
||
| 307 | 18188fcc | Eric Allman | </p>
|
| 308 | 9eeb635c | Eric Allman | <hr size="2" width="100%"> |
| 309 | 18188fcc | Eric Allman | <p> </p> |
| 310 | <h4>Name</h4> |
||
| 311 | 26fa111b | Eric Allman | GET /gdp/v1/gcl/<gcl_name>?recno=<#>&nrecs=<#> — |
| 312 | get a series of records<br>
|
||
| 313 | 18188fcc | Eric Allman | <h4>Request Data</h4> |
| 314 | none<br>
|
||
| 315 | <h4>Response</h4> |
||
| 316 | 200 OK<br>
|
||
| 317 | 26fa111b | Eric Allman | <pre> [<br> {<br> "recno": <integer>,<br> "timestamp": <timestamp>,<br> "value": <record value><br> },<br> ...<br> ]</pre> |
| 318 | 18188fcc | Eric Allman | 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 | 26fa111b | Eric Allman | 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 | a29668f9 | Eric Allman | parameter is optional and defaults to 1.</p>
|
| 324 | <p>The <var>nrecs</var> parameter is not implemented at this time.<br> |
||
| 325 | 18188fcc | Eric Allman | </p>
|
| 326 | 9eeb635c | Eric Allman | <hr size="2" width="100%"> |
| 327 | 18188fcc | Eric Allman | <h4>Name</h4> |
| 328 | GET |
||
| 329 | /gdp/v1/gcl/gcl_id?recno=<#>&nrecs=<#>&timeout=<seconds> |
||
| 330 | |||
| 331 | 591ae6e9 | Eric Allman | |
| 332 | 9eeb635c | Eric Allman | |
| 333 | 2b29bb77 | Eric Allman | |
| 334 | 26fa111b | Eric Allman | — monitor a GCL<br> |
| 335 | 18188fcc | Eric Allman | <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 | 26fa111b | Eric Allman | <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 | 9148e726 | Eric Allman | starting record number is not specified, it starts from the beginning.</p><h4>Notes</h4> |
| 354 | a29668f9 | Eric Allman | <p>The <var>nrecs</var> and <var>timeout</var> parameters are not |
| 355 | implemented at this time.</p>
|
||
| 356 | 26fa111b | Eric Allman | <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 | 18188fcc | Eric Allman | </p>
|
| 364 | 9eeb635c | Eric Allman | <hr size="2" width="100%"> |
| 365 | 18188fcc | Eric Allman | <h4>Name</h4> |
| 366 | 26fa111b | Eric Allman | GET /gdp/v1/post/gcl/<gcl_name>?<arguments> — add data to |
| 367 | a GCL (<i><b>not REST compliant</b></i>)<br> |
||
| 368 | 18188fcc | Eric Allman | <h4>Description</h4> |
| 369 | 26fa111b | Eric Allman | <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 | 18188fcc | Eric Allman | </p>
|
| 372 | <p> </p> |
||
| 373 | 9eeb635c | Eric Allman | <hr size="2" width="100%"> |
| 374 | a29668f9 | Eric Allman | <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 | 9eeb635c | Eric Allman | <h4>Name</h4> |
| 390 | 26fa111b | Eric Allman | POST /gdp/v1/kv — add data to key-value store<br> |
| 391 | 9eeb635c | Eric Allman | <h4>Description</h4> |
| 392 | 26fa111b | Eric Allman | <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 | 9eeb635c | Eric Allman | <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 | a3aab530 | Rick Pratt | <a id="Summary"><h2> 4 Summary</h2></a> |
| 409 | 26fa111b | Eric Allman | <p>This is just a quick recap of the material presented above. All |
| 410 | 9148e726 | Eric Allman | URLs begin with "<code>/gdp/v1/</code>".<br> |
| 411 | 18188fcc | Eric Allman | </p>
|
| 412 | 26fa111b | Eric Allman | <table border="1" cellpadding="2" cellspacing="2" width="100%"> |
| 413 | 18188fcc | Eric Allman | <tbody>
|
| 414 | <tr>
|
||
| 415 | 04ad7859 | Rick Pratt | <td valign="top"><H4>Scope</H4> |
| 416 | </td>
|
||
| 417 | <td valign="top"><H3>Method</H3> |
||
| 418 | 18188fcc | Eric Allman | </td>
|
| 419 | 04ad7859 | Rick Pratt | <td valign="top"><H3>URI Path</H3> |
| 420 | 18188fcc | Eric Allman | </td>
|
| 421 | 04ad7859 | Rick Pratt | <td valign="top"><H3>Description</H3> |
| 422 | 18188fcc | Eric Allman | </td>
|
| 423 | </tr>
|
||
| 424 | <tr>
|
||
| 425 | 04ad7859 | Rick Pratt | <td valign="top">GDP<br> |
| 426 | </td>
|
||
| 427 | 18188fcc | Eric Allman | <td valign="top">GET<br> |
| 428 | </td>
|
||
| 429 | <td valign="top">gcl<br> |
||
| 430 | </td>
|
||
| 431 | 04ad7859 | Rick Pratt | <td valign="top"><span style="text-decoration: line-through;">Lists existing GCLs</span> <br>[405 Method Not Allowed]<br> |
| 432 | 18188fcc | Eric Allman | </td>
|
| 433 | </tr>
|
||
| 434 | <tr>
|
||
| 435 | 04ad7859 | Rick Pratt | <td valign="top">GDP<br> |
| 436 | </td>
|
||
| 437 | 18188fcc | Eric Allman | <td valign="top">POST<br> |
| 438 | </td>
|
||
| 439 | <td valign="top">gcl<br> |
||
| 440 | </td>
|
||
| 441 | 04ad7859 | Rick Pratt | <td valign="top">Create new GCL with random name<br> |
| 442 | 18188fcc | Eric Allman | </td>
|
| 443 | </tr>
|
||
| 444 | <tr>
|
||
| 445 | 04ad7859 | Rick Pratt | <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 | 18188fcc | Eric Allman | </td>
|
| 459 | <td valign="top">gcl<br> |
||
| 460 | </td>
|
||
| 461 | 04ad7859 | Rick Pratt | <td valign="top"><span style="text-decoration: line-through;">Delete GCL</span><br>[405 Method Not Allowed]<br> |
| 462 | 18188fcc | Eric Allman | </td>
|
| 463 | </tr>
|
||
| 464 | <tr>
|
||
| 465 | 04ad7859 | Rick Pratt | <td valign="top">GCL<br> |
| 466 | </td>
|
||
| 467 | 18188fcc | Eric Allman | <td valign="top">GET<br> |
| 468 | </td>
|
||
| 469 | <td valign="top">gcl/<id><br> |
||
| 470 | </td>
|
||
| 471 | dfe937e2 | Rick Pratt | <td valign="top"><span style="text-decoration: line-through;">GCL <id> read metadata</span><br>[405 Method Not Allowed]<br> |
| 472 | 18188fcc | Eric Allman | </td>
|
| 473 | </tr>
|
||
| 474 | <tr>
|
||
| 475 | 04ad7859 | Rick Pratt | <td valign="top">GCL<br> |
| 476 | </td>
|
||
| 477 | 18188fcc | Eric Allman | <td valign="top">POST</td> |
| 478 | <td valign="top">gcl/<id><br> |
||
| 479 | </td>
|
||
| 480 | dfe937e2 | Rick Pratt | <td valign="top">GCL <id> append record<br> |
| 481 | 18188fcc | Eric Allman | </td>
|
| 482 | </tr>
|
||
| 483 | <tr>
|
||
| 484 | 04ad7859 | Rick Pratt | <td valign="top">GCL<br> |
| 485 | </td>
|
||
| 486 | 18188fcc | Eric Allman | <td valign="top">PUT<br> |
| 487 | </td>
|
||
| 488 | 04ad7859 | Rick Pratt | <td valign="top">gcl/<id>?recno=<#><br> |
| 489 | 18188fcc | Eric Allman | </td>
|
| 490 | dfe937e2 | Rick Pratt | <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 | 18188fcc | Eric Allman | </td>
|
| 492 | </tr>
|
||
| 493 | <tr>
|
||
| 494 | 04ad7859 | Rick Pratt | <td valign="top">GCL<br> |
| 495 | </td>
|
||
| 496 | 18188fcc | Eric Allman | <td valign="top">DELETE<br> |
| 497 | </td>
|
||
| 498 | <td valign="top">gcl/<id><br> |
||
| 499 | </td>
|
||
| 500 | dfe937e2 | Rick Pratt | <td valign="top"><span style="text-decoration: line-through;">GCL <id> delete record</span><br>Deprecated: GCL is append-only by design<br> |
| 501 | 18188fcc | Eric Allman | </td>
|
| 502 | </tr>
|
||
| 503 | <tr>
|
||
| 504 | 04ad7859 | Rick Pratt | <td valign="top">GCL<br> |
| 505 | </td>
|
||
| 506 | 18188fcc | Eric Allman | <td valign="top">GET<br> |
| 507 | </td>
|
||
| 508 | <td valign="top">gcl/<id>?recno=<#><br> |
||
| 509 | </td>
|
||
| 510 | dfe937e2 | Rick Pratt | <td valign="top">GCL <id> read record at recno<br>(returns raw data)<br> |
| 511 | 18188fcc | Eric Allman | </td>
|
| 512 | </tr>
|
||
| 513 | <tr>
|
||
| 514 | 04ad7859 | Rick Pratt | <td valign="top">GCL<br> |
| 515 | </td>
|
||
| 516 | 18188fcc | Eric Allman | <td valign="top">GET<br> |
| 517 | </td>
|
||
| 518 | <td valign="top">gcl/<id>?recno=<#>&nrecs=<#><br> |
||
| 519 | </td>
|
||
| 520 | dfe937e2 | Rick Pratt | <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 | 18188fcc | Eric Allman | </td>
|
| 522 | </tr>
|
||
| 523 | <tr>
|
||
| 524 | 04ad7859 | Rick Pratt | <td valign="top">GCL<br> |
| 525 | </td>
|
||
| 526 | 18188fcc | Eric Allman | <td valign="top">GET<br> |
| 527 | </td>
|
||
| 528 | <td valign="top">gcl/<id>?timeout=<#><br> |
||
| 529 | </td>
|
||
| 530 | dfe937e2 | Rick Pratt | <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 | 18188fcc | Eric Allman | </td>
|
| 532 | </tr>
|
||
| 533 | <tr>
|
||
| 534 | 04ad7859 | Rick Pratt | <td valign="top">GCL<br> |
| 535 | </td>
|
||
| 536 | 18188fcc | Eric Allman | <td valign="top">GET<br> |
| 537 | </td>
|
||
| 538 | <td valign="top">put/gcl/<id>?<arguments><br> |
||
| 539 | </td>
|
||
| 540 | dfe937e2 | Rick Pratt | <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 | 18188fcc | Eric Allman | </td>
|
| 542 | </tr>
|
||
| 543 | 9eeb635c | Eric Allman | <tr>
|
| 544 | 04ad7859 | Rick Pratt | <td valign="top">RESTful Server<br> |
| 545 | </td>
|
||
| 546 | 9eeb635c | Eric Allman | <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 | 04ad7859 | Rick Pratt | <td valign="top">RESTful Server<br> |
| 555 | </td>
|
||
| 556 | 9eeb635c | Eric Allman | <td valign="top">GET<br> |
| 557 | </td>
|
||
| 558 | <td valign="top">kv/<key><br> |
||
| 559 | </td>
|
||
| 560 | 26fa111b | Eric Allman | <td valign="top">Return JSON information associated with <key> |
| 561 | in the key-value store<br>
|
||
| 562 | 9eeb635c | Eric Allman | </td>
|
| 563 | </tr>
|
||
| 564 | 18188fcc | Eric Allman | </tbody>
|
| 565 | </table>
|
||
| 566 | <p><br> |
||
| 567 | </p>
|
||
| 568 | <h2>4 Unresolved Issues</h2> |
||
| 569 | 26fa111b | Eric Allman | <p>Do subscriptions wait until all data is ready to return, or does it
|
| 570 | 04ad7859 | Rick Pratt | 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> |