these tasks. In general, everything that can be done with a PUT or DELETE can
also be done with a POST.
-Tahoe's web API is designed for two different consumers. The first is a
-program that needs to manipulate the virtual file system. Such programs are
+Tahoe's web API is designed for two different kinds of consumer. The first is
+a program that needs to manipulate the virtual file system. Such programs are
expected to use the RESTful interface described above. The second is a human
using a standard web browser to work with the filesystem. This user is given
a series of HTML pages with links to download files, and forms that use POST
actions to upload, rename, and delete files.
When an error occurs, the HTTP response code will be set to an appropriate
-400-series code (like 404 for an unknown childname, or 400 Gone when a file
-is unrecoverable due to insufficient shares), and the HTTP response body will
-usually contain a few lines of explanation as to the cause of the error and
-possible responses. Unusual exceptions may result in a 500 Internal Server
-Error as a catch-all, with a default response body will contain a
-Nevow-generated HTML-ized representation of the Python exception stack trace
+400-series code (like 404 Not Found for an unknown childname, or 400 Bad Request
+when the parameters to a webapi operation are invalid), and the HTTP response
+body will usually contain a few lines of explanation as to the cause of the
+error and possible responses. Unusual exceptions may result in a
+500 Internal Server Error as a catch-all, with a default response body containing
+a Nevow-generated HTML-ized representation of the Python exception stack trace
that caused the problem. CLI programs which want to copy the response body to
stderr should provide an "Accept: text/plain" header to their requests to get
a plain text stack trace instead. If the Accept header contains */*, or
read- and write- caps, which start with "URI:SSK", and give access to mutable
files.
-(later versions of Tahoe will make these strings shorter, and will remove the
+(Later versions of Tahoe will make these strings shorter, and will remove the
unfortunate colons, which must be escaped when these caps are embedded in
-URLs).
+URLs.)
To refer to any Tahoe object through the web API, you simply need to combine
a prefix (which indicates the HTTP server to use) with the cap (which
http://127.0.0.1:3456/uri/ + $CAP
So, to access the directory named above (which happens to be the
-publically-writable sample directory on the Tahoe test grid, described at
+publically-writeable sample directory on the Tahoe test grid, described at
http://allmydata.org/trac/tahoe/wiki/TestGrid), the URL would be:
http://127.0.0.1:3456/uri/URI%3ADIR2%3Adjrdkfawoqihigoett4g6auz6a%3Ajx5mplfpwexnoqff7y5e4zjus4lidm76dcuarpct7cckorh2dpgq/
representable as such.
All Tahoe operations that refer to existing files or directories must include
-a suitable read- or write- cap in the URL: the wapi server won't add one
+a suitable read- or write- cap in the URL: the webapi server won't add one
for you. If you don't know the cap, you can't access the file. This allows
-the security properties of Tahoe caps to be extended across the wapi
+the security properties of Tahoe caps to be extended across the webapi
interface.
== Slow Operations, Progress, and Cancelling ==
since the operation completed) will remain valid for ten minutes.
Many "slow" operations can begin to use unacceptable amounts of memory when
-operation on large directory structures. The memory usage increases when the
+operating on large directory structures. The memory usage increases when the
ophandle is polled, as the results must be copied into a JSON string, sent
over the wire, then parsed by a client. So, as an alternative, many "slow"
operations have streaming equivalents. These equivalents do not use operation
retrieve the same contents that were just uploaded. This will create any
necessary intermediate subdirectories.
- To use the /uri/$FILECAP form, $FILECAP be a write-cap for a mutable file.
+ To use the /uri/$FILECAP form, $FILECAP must be a write-cap for a mutable file.
In the /uri/$DIRCAP/[SUBDIRS../]FILENAME form, if the target file is a
- writable mutable file, that files contents will be overwritten in-place. If
+ writeable mutable file, that file's contents will be overwritten in-place. If
it is a read-cap for a mutable file, an error will occur. If it is an
immutable file, the old file will be discarded, and a new one will be put in
its place.
PUT /uri
This uploads a file, and produces a file-cap for the contents, but does not
- attach the file into the virtual drive. No directories will be modified by
+ attach the file into the filesystem. No directories will be modified by
this operation. The file-cap is returned as the body of the HTTP response.
If "mutable=true" is in the query arguments, the operation will create a
Create a new empty directory and return its write-cap as the HTTP response
body. This does not make the newly created directory visible from the
- virtual drive. The "PUT" operation is provided for backwards compatibility:
+ filesystem. The "PUT" operation is provided for backwards compatibility:
new code should use POST.
POST /uri?t=mkdir-with-children
"linkcrtime": 1202777696.7564139,
"linkmotime": 1202777696.7564139,
} } } ]
- }
+ }
For forward-compatibility, a mutable directory can also contain caps in
a format that is unknown to the webapi server. When such caps are retrieved
the immediate parent directory already has a a child named NAME.
Note that the name= argument must be passed as a queryarg, because the POST
- request body is used for the initial children JSON.
+ request body is used for the initial children JSON.
POST /uri/$DIRCAP/[SUBDIRS../]?t=mkdir-immutable&name=NAME
Then the rw_uri field will be present in the information about a directory
if and only if you have read-write access to that directory. The verify_uri
- field will be presend if and only if the object has a verify-cap
+ field will be present if and only if the object has a verify-cap
(non-distributed LIT files do not have verify-caps).
==== About the metadata ====
link points.
4. Also, quite apart from Tahoe, you might be confused about the meaning of
- the 'ctime' in unix local filesystems, which people sometimes think means
- file creation time, but which actually means, in unix local filesystems, the
+ the 'ctime' in UNIX local filesystems, which people sometimes think means
+ file creation time, but which actually means, in UNIX local filesystems, the
most recent time that the file contents or the file metadata (such as owner,
permission bits, extended attributes, etc.) has changed. Note that although
- 'ctime' does not mean file creation time in Unix, it does mean link creation
+ 'ctime' does not mean file creation time in UNIX, it does mean link creation
time in Tahoe, unless the "tahoe backup" command has been used on that link,
in which case it means something about the local filesystem file which
corresponds to the Tahoe file which is pointed at by the link. It means
Windows) or file-contents-or-metadata-update-time of the local file (if
"tahoe backup" was run on a different operating system).
-
=== Attaching an existing File or Directory by its read- or write- cap ===
PUT /uri/$DIRCAP/[SUBDIRS../]CHILDNAME?t=uri
if there is already an object at the given location, rather than
overwriting the existing object. To allow the operation to overwrite a
file, but return an error when trying to overwrite a directory, use
- "replace=only-files" (this behavior is closer to the traditional unix "mv"
+ "replace=only-files" (this behavior is closer to the traditional UNIX "mv"
command). Note that "true", "t", and "1" are all synonyms for "True", and
"false", "f", and "0" are synonyms for "False", and the parameter is
case-insensitive.
+
+ Note that this operation does not take its child cap in the form of
+ separate "rw_uri" and "ro_uri" fields. Therefore, it cannot accept a
+ child cap in a format unknown to the webapi server, because the server
+ is not able to attenuate an unknown write cap to a read cap.
=== Adding multiple files or directories to a parent directory at once ===
The object will only become completely unreachable once 1: there are no
reachable directories that reference it, and 2: nobody is holding a read-
or write- cap to the object. (This behavior is very similar to the way
- hardlinks and anonymous files work in traditional unix filesystems).
+ hardlinks and anonymous files work in traditional UNIX filesystems).
This operation will not modify more than a single directory. Intermediate
directories which were implicitly created by PUT or POST methods will *not*
POST /uri?t=upload
This uploads a file, and produces a file-cap for the contents, but does not
- attach the file into the virtual drive. No directories will be modified by
+ attach the file into the filesystem. No directories will be modified by
this operation.
The file must be provided as the "file" field of an HTML encoded form body,
== Static Files in /public_html ==
-The wapi server will take any request for a URL that starts with /static
+The webapi server will take any request for a URL that starts with /static
and serve it from a configurable directory which defaults to
$BASEDIR/public_html . This is configured by setting the "[node]web.static"
value in $BASEDIR/tahoe.cfg . If this is left at the default value of
served with the contents of the file $BASEDIR/public_html/subdir/foo.html .
This can be useful to serve a javascript application which provides a
-prettier front-end to the rest of the Tahoe wapi.
+prettier front-end to the rest of the Tahoe webapi.
-== safety and security issues -- names vs. URIs ==
+== Safety and security issues -- names vs. URIs ==
Summary: use explicit file- and dir- caps whenever possible, to reduce the
potential for surprises when the filesystem structure is changed.
Tahoe nodes implement internal serialization to make sure that a single Tahoe
node cannot conflict with itself. For example, it is safe to issue two
-directory modification requests to a single tahoe node's wapi server at the
+directory modification requests to a single tahoe node's webapi server at the
same time, because the Tahoe node will internally delay one of them until
after the other has finished being applied. (This feature was introduced in
Tahoe-1.1; back with Tahoe-1.0 the web client was responsible for serializing
projects / tahoe-lafs / tahoe-lafs.git / commitdiff