ExternalVendorCode/tahoe-lafs
1
0
Fork 0
mirror of https://github.com/tahoe-lafs/tahoe-lafs.git synced 2025-01-31 08:25:35 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: webapi.txt edits to explain a few things better, adjust indentation, editing

Browse Source
This commit is contained in:
Zooko O'Whielacronx 2009-04-11 15:48:28 -07:00
parent 5b02896307
commit 664b69dd8d
1 changed files with 47 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
docs/frontends/webapi.txt
View File

@ -381,12 +381,24 @@ GET /uri/$DIRCAP/[SUBDIRS../]SUBDIR?t=json
GET /uri/$DIRCAP/[SUBDIRS../]FILENAME?t=json
This returns a machine-parseable JSON-encoded description of the given
object. The JSON always contains a list, and the first element of the list
is always a flag that indicates whether the referenced object is a file or a
directory. If it is a file, then the information includes file size and URI,
like this:
object. The JSON always contains a list, and the first element of the list is
always a flag that indicates whether the referenced object is a file or a
directory. If it is a capability to a file, then the information includes
file size and URI, like this:
GET /uri/$FILECAP?t=json :
[ "filenode", {
"ro_uri": file_uri,
"verify_uri": verify_uri,
"size": bytes,
"mutable": false,
} ]
If it is a capability to a directory followed by a path from that directory
to a file, then the information also includes metadata from the link to the
file in the parent directory, like this:
GET /uri/$DIRCAP/[SUBDIRS../]FILENAME?t=json :
[ "filenode", { "ro_uri": file_uri,
@ -446,26 +458,26 @@ GET /uri/$DIRCAP/[SUBDIRS../]FILENAME?t=json
PUT /uri/$DIRCAP/[SUBDIRS../]CHILDNAME?t=uri
This attaches a child object (either a file or directory) to a specified
location in the virtual filesystem. The child object is referenced by its
read- or write- cap, as provided in the HTTP request body. This will create
intermediate directories as necessary.
This attaches a child object (either a file or directory) to a specified
location in the virtual filesystem. The child object is referenced by its
read- or write- cap, as provided in the HTTP request body. This will create
intermediate directories as necessary.
This is similar to a UNIX hardlink: by referencing a previously-uploaded
file (or previously-created directory) instead of uploading/creating a new
one, you can create two references to the same object.
This is similar to a UNIX hardlink: by referencing a previously-uploaded file
(or previously-created directory) instead of uploading/creating a new one,
you can create two references to the same object.
The read- or write- cap of the child is provided in the body of the HTTP
request, and this same cap is returned in the response body.
The read- or write- cap of the child is provided in the body of the HTTP
request, and this same cap is returned in the response body.
The default behavior is to overwrite any existing object at the same
location. To prevent this (and make the operation return an error instead of
overwriting), add a "replace=false" argument, as "?t=uri&replace=false".
With replace=false, this operation will return an HTTP 409 "Conflict" error
if there is already an object at the given location, rather than overwriting
the existing object. Note that "true", "t", and "1" are all synonyms for
"True", and "false", "f", and "0" are synonyms for "False". the parameter is
case-insensitive.
The default behavior is to overwrite any existing object at the same
location. To prevent this (and make the operation return an error instead of
overwriting), add a "replace=false" argument, as "?t=uri&replace=false". With
replace=false, this operation will return an HTTP 409 "Conflict" error if
there is already an object at the given location, rather than overwriting the
existing object. Note that "true", "t", and "1" are all synonyms for "True",
and "false", "f", and "0" are synonyms for "False". the parameter is
case-insensitive.
=== Deleting a File or Directory ===
@ -1364,24 +1376,23 @@ prettier front-end to the rest of the Tahoe wapi.
== safety and security issues -- names vs. URIs ==
Summary: use explicit file- and dir- caps whenever possible, to reduce the
potential for surprises when the virtual drive is changed while you aren't
looking.
potential for surprises when the filesystem structure is changed.
The vdrive provides a mutable filesystem, but the ways that the filesystem
can change are limited. The only thing that can change is that the mapping
from child names to child objects that each directory contains can be changed
by adding a new child name pointing to an object, removing an existing child
name, or changing an existing child name to point to a different object.
Tahoe provides a mutable filesystem, but the ways that the filesystem can
change are limited. The only thing that can change is that the mapping from
child names to child objects that each directory contains can be changed by
adding a new child name pointing to an object, removing an existing child name,
or changing an existing child name to point to a different object.
Obviously if you query tahoe for information about the filesystem and then
act upon the filesystem (such as by getting a listing of the contents of a
Obviously if you query Tahoe for information about the filesystem and then act
to change the filesystem (such as by getting a listing of the contents of a
directory and then adding a file to the directory), then the filesystem might
have been changed after you queried it and before you acted upon it.
However, if you use the URI instead of the pathname of an object when you act
upon the object, then the only change that can happen is when the object is a
directory then the set of child names it has might be different. If, on the
other hand, you act upon the object using its pathname, then a different
object might be in that place, which can result in more kinds of surprises.
have been changed after you queried it and before you acted upon it. However,
if you use the URI instead of the pathname of an object when you act upon the
object, then the only change that can happen is if the object is a directory
then the set of child names it has might be different. If, on the other hand,
you act upon the object using its pathname, then a different object might be in
that place, which can result in more kinds of surprises.
For example, suppose you are writing code which recursively downloads the
contents of a directory. The first thing your code does is fetch the listing