Ticket #118: webapi.warner1.diff
| File webapi.warner1.diff, 6.5 KB (added by warner, at 2007-08-23T19:41:42Z) |
|---|
-
webapi-new.txt
old new 19 19 "ssl:8011:privateKey=mykey.pem:certKey=cert.pem" would run an SSL server. See 20 20 twisted.application.strports for more details. 21 21 22 If $NODEDIR/webpassword exists, it will be used (somehow) to require HTTP23 Digest Authentication for all webserver connections. XXX specify how24 25 22 b. file names 26 23 27 24 The node provides some small number of "virtual drives". In the 0.5 … … 58 55 59 56 c. URIs 60 57 58 From the "URIs" chapter in architecture.txt, recall that each file and 59 directory has a unique "URI". This is a string which provides a secure 60 reference to the file or directory: if you know the URI, you can retrieve 61 (and possibly modify) the object. If you don't know the URI, you cannot 62 access the object. 63 61 64 A separate top-level namespace ("uri/" instead of "vdrive/") is used to 62 65 access to files and directories directly by URI, rather than by going through 63 the vdrive.66 the pathnames in the vdrive. 64 67 65 68 For example, this identifies a file or directory: 66 69 … … 72 75 http://localhost:8011/uri/$URI/Pictures/tractors.jpg 73 76 74 77 In the following examples, "$URL" is a shorthand for a URL like the ones 75 above, either with "vdrive/" a s the top level and a sequence of76 s lash-separated pathnames following, or with "uri/" as the top level,77 followed by a URI, optionally followed by a sequence of slash-separated 78 pathnames.78 above, either with "vdrive/" and a vdrive name as the top level and a 79 sequence of slash-separated pathnames following, or with "uri/" as the top 80 level, followed by a URI, optionally followed by a sequence of 81 slash-separated pathnames. 79 82 80 83 Now, what can we do with these URLs? By varying the HTTP method 81 84 (GET/PUT/POST/DELETE) and by appending a type-indicating query argument, we … … 86 89 GET $URL?t=json 87 90 88 91 This returns machine-parseable information about the indicated file or 89 directory in the HTTP response body. This information contains a flag that 90 indicates whether the thing is a file or a directory. 92 directory in the HTTP response body. The JSON always contains a list, and 93 the first element of the list is always a flag that indicates whether the 94 referenced object is a file or a directory. 91 95 92 96 If it is a file, then the information includes file size and URI, like 93 97 this: … … 127 131 response. 128 132 129 133 If the indicated object a directory, then this returns an HTML page, 130 intended to be used by humans, which contains HREF links to all files and 131 directories reachable from this directory. These HREF links do not have a 132 t= argument, meaning that a human who follows them will get pages also 133 meant for a human. It also contains forms to upload new files, and to 134 delete files and directories. These forms use POST methods to do their job. 134 intended to be displayed to a human by a web browser, which contains HREF 135 links to all files and directories reachable from this directory. These 136 HREF links do not have a t= argument, meaning that a human who follows them 137 will get pages also meant for a human. It also contains forms to upload new 138 files, and to delete files and directories. These forms use POST methods to 139 do their job. 135 140 136 141 You can add the "save=true" argument, which adds a 'Content-Disposition: 137 142 attachment' header to prompt most web browsers to save the file to disk 138 143 rather than attempting to display it. 139 144 140 A filename (from which a MIME type can be derived) can be specified using a141 'filename=' query argument. This is especially useful if the $URL does not142 end with the name of the file (because it instead ends with the identifier143 of the file). This filename is also the one used if the 'save=true'144 a rgument is set. For example:145 A filename (from which MIME type can be derived, for use in the 146 Content-Type header) can be specified using a 'filename=' query argument. 147 This is especially useful if the $URL does not end with the name of the 148 file (e.g. if it ends with the URI of the file instead). This filename is 149 also the one used if the 'save=true' argument is set. For example: 145 150 146 151 GET http://localhost:8011/uri/$TRACTORS_URI?filename=tractors.jpg 147 152 … … 176 181 177 182 The URI of the child is provided in the body of the HTTP request. 178 183 179 There is an optional "? overwrite=" param whose value can be "true", "t",180 " 1", "false", "f", or "0" (case-insensitive), and which defaults to "true".181 Ifthe indicated directory already contains the given child name, then if182 overwrite is true then the value of that name is changed to be the new URI.183 If overwrite is false then an error is returned. XXX specify the error184 There is an optional "?replace=" param whose value can be "true", "t", "1", 185 "false", "f", or "0" (case-insensitive), and which defaults to "true". If 186 the indicated directory already contains the given child name, then if 187 replace is True then the value of that name is changed to be the new URI. 188 If replace is False then an HTTP 409 "Conflict" error is returned. 184 189 185 190 This can be used to attach a shared directory (a directory that other 186 191 people can read or write) to the vdrive. Intermediate directories, if any, … … 203 208 they can continue to access the resource through the URI. Only if a person 204 209 is not in possession of the URI, and they do not have access to any 205 210 directories which contain names pointing to this resource, are they 206 prevented from accessing the resource. 211 prevented from accessing the resource. (this behavior is very similar to 212 the way hardlinks and anonymous files work in traditional unix 213 filesystems). 207 214 208 215 2. convenience methods 209 216 … … 221 228 the client is not obligated to do anything with the URI. According to the 222 229 HTTP/1.1 specification (rfc2616), this should return a 200 (OK) code when 223 230 modifying an existing file, and a 201 (Created) code when creating a new 224 file. 231 file. (TODO: as of 0.5, the web server only returns 200, never 201). 225 232 226 233 To use this, run 'curl -T localfile http://localhost:8011/vdrive/global/newfile' 227 234 … … 260 267 If your recursive algorithm uses the uri of the child instead of the name of 261 268 the child, then those kinds of mistakes just can't happen. Note that both the 262 269 child's name and the child's URI are included in the results of listing the 263 parent directory, so it isn't harder to use the URI for this purpose.270 parent directory, so it isn't any harder to use the URI for this purpose. 264 271 265 272 In general, use names if you want "whatever object (whether file or 266 273 directory) is found by following this name (or sequence of names) when my
