|
|
@ -70,20 +70,20 @@ delete), because otherwise a regular web browser has no way to accomplish
|
|
|
|
these tasks. In general, everything that can be done with a PUT or DELETE can
|
|
|
|
these tasks. In general, everything that can be done with a PUT or DELETE can
|
|
|
|
also be done with a POST.
|
|
|
|
also be done with a POST.
|
|
|
|
|
|
|
|
|
|
|
|
Tahoe's web API is designed for two different consumers. The first is a
|
|
|
|
Tahoe's web API is designed for two different kinds of consumer. The first is
|
|
|
|
program that needs to manipulate the virtual file system. Such programs are
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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
|
|
|
|
a series of HTML pages with links to download files, and forms that use POST
|
|
|
|
actions to upload, rename, and delete files.
|
|
|
|
actions to upload, rename, and delete files.
|
|
|
|
|
|
|
|
|
|
|
|
When an error occurs, the HTTP response code will be set to an appropriate
|
|
|
|
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
|
|
|
|
400-series code (like 404 Not Found for an unknown childname, or 400 Bad Request
|
|
|
|
is unrecoverable due to insufficient shares), and the HTTP response body will
|
|
|
|
when the parameters to a webapi operation are invalid), and the HTTP response
|
|
|
|
usually contain a few lines of explanation as to the cause of the error and
|
|
|
|
body will usually contain a few lines of explanation as to the cause of the
|
|
|
|
possible responses. Unusual exceptions may result in a 500 Internal Server
|
|
|
|
error and possible responses. Unusual exceptions may result in a
|
|
|
|
Error as a catch-all, with a default response body will contain a
|
|
|
|
500 Internal Server Error as a catch-all, with a default response body containing
|
|
|
|
Nevow-generated HTML-ized representation of the Python exception stack trace
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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
|
|
|
|
a plain text stack trace instead. If the Accept header contains */*, or
|
|
|
@ -108,9 +108,9 @@ give read-only access to a directory. Finally there are also mutable file
|
|
|
|
read- and write- caps, which start with "URI:SSK", and give access to mutable
|
|
|
|
read- and write- caps, which start with "URI:SSK", and give access to mutable
|
|
|
|
files.
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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
|
|
|
|
a prefix (which indicates the HTTP server to use) with the cap (which
|
|
|
@ -121,7 +121,7 @@ listening on this port:
|
|
|
|
http://127.0.0.1:3456/uri/ + $CAP
|
|
|
|
http://127.0.0.1:3456/uri/ + $CAP
|
|
|
|
|
|
|
|
|
|
|
|
So, to access the directory named above (which happens to be the
|
|
|
|
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://allmydata.org/trac/tahoe/wiki/TestGrid), the URL would be:
|
|
|
|
|
|
|
|
|
|
|
|
http://127.0.0.1:3456/uri/URI%3ADIR2%3Adjrdkfawoqihigoett4g6auz6a%3Ajx5mplfpwexnoqff7y5e4zjus4lidm76dcuarpct7cckorh2dpgq/
|
|
|
|
http://127.0.0.1:3456/uri/URI%3ADIR2%3Adjrdkfawoqihigoett4g6auz6a%3Ajx5mplfpwexnoqff7y5e4zjus4lidm76dcuarpct7cckorh2dpgq/
|
|
|
@ -199,9 +199,9 @@ contain unicode filenames, and cannot contain binary strings that are not
|
|
|
|
representable as such.
|
|
|
|
representable as such.
|
|
|
|
|
|
|
|
|
|
|
|
All Tahoe operations that refer to existing files or directories must include
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
interface.
|
|
|
|
|
|
|
|
|
|
|
|
== Slow Operations, Progress, and Cancelling ==
|
|
|
|
== Slow Operations, Progress, and Cancelling ==
|
|
|
@ -275,7 +275,7 @@ If a retain-for= argument is not used, the default handle lifetimes are:
|
|
|
|
since the operation completed) will remain valid for ten minutes.
|
|
|
|
since the operation completed) will remain valid for ten minutes.
|
|
|
|
|
|
|
|
|
|
|
|
Many "slow" operations can begin to use unacceptable amounts of memory when
|
|
|
|
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
|
|
|
|
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"
|
|
|
|
over the wire, then parsed by a client. So, as an alternative, many "slow"
|
|
|
|
operations have streaming equivalents. These equivalents do not use operation
|
|
|
|
operations have streaming equivalents. These equivalents do not use operation
|
|
|
@ -315,10 +315,10 @@ PUT /uri/$DIRCAP/[SUBDIRS../]FILENAME
|
|
|
|
retrieve the same contents that were just uploaded. This will create any
|
|
|
|
retrieve the same contents that were just uploaded. This will create any
|
|
|
|
necessary intermediate subdirectories.
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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
|
|
|
|
immutable file, the old file will be discarded, and a new one will be put in
|
|
|
|
its place.
|
|
|
|
its place.
|
|
|
@ -337,7 +337,7 @@ PUT /uri/$DIRCAP/[SUBDIRS../]FILENAME
|
|
|
|
PUT /uri
|
|
|
|
PUT /uri
|
|
|
|
|
|
|
|
|
|
|
|
This uploads a file, and produces a file-cap for the contents, but does not
|
|
|
|
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.
|
|
|
|
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
|
|
|
|
If "mutable=true" is in the query arguments, the operation will create a
|
|
|
@ -351,7 +351,7 @@ PUT /uri?t=mkdir
|
|
|
|
|
|
|
|
|
|
|
|
Create a new empty directory and return its write-cap as the HTTP response
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
new code should use POST.
|
|
|
|
|
|
|
|
|
|
|
|
POST /uri?t=mkdir-with-children
|
|
|
|
POST /uri?t=mkdir-with-children
|
|
|
@ -392,7 +392,7 @@ POST /uri?t=mkdir-with-children
|
|
|
|
"linkcrtime": 1202777696.7564139,
|
|
|
|
"linkcrtime": 1202777696.7564139,
|
|
|
|
"linkmotime": 1202777696.7564139,
|
|
|
|
"linkmotime": 1202777696.7564139,
|
|
|
|
} } } ]
|
|
|
|
} } } ]
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
For forward-compatibility, a mutable directory can also contain caps in
|
|
|
|
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
|
|
|
|
a format that is unknown to the webapi server. When such caps are retrieved
|
|
|
@ -522,7 +522,7 @@ POST /uri/$DIRCAP/[SUBDIRS../]?t=mkdir-with-children&name=NAME
|
|
|
|
the immediate parent directory already has a a child named NAME.
|
|
|
|
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
|
|
|
|
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
|
|
|
|
POST /uri/$DIRCAP/[SUBDIRS../]?t=mkdir-immutable&name=NAME
|
|
|
|
|
|
|
|
|
|
|
@ -625,7 +625,7 @@ GET /uri/$DIRCAP/[SUBDIRS../]FILENAME?t=json
|
|
|
|
|
|
|
|
|
|
|
|
Then the rw_uri field will be present in the information about a directory
|
|
|
|
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
|
|
|
|
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).
|
|
|
|
(non-distributed LIT files do not have verify-caps).
|
|
|
|
|
|
|
|
|
|
|
|
==== About the metadata ====
|
|
|
|
==== About the metadata ====
|
|
|
@ -701,11 +701,11 @@ GET /uri/$DIRCAP/[SUBDIRS../]FILENAME?t=json
|
|
|
|
link points.
|
|
|
|
link points.
|
|
|
|
|
|
|
|
|
|
|
|
4. Also, quite apart from Tahoe, you might be confused about the meaning of
|
|
|
|
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
|
|
|
|
the 'ctime' in UNIX local filesystems, which people sometimes think means
|
|
|
|
file creation time, but which actually means, in unix local filesystems, the
|
|
|
|
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,
|
|
|
|
most recent time that the file contents or the file metadata (such as owner,
|
|
|
|
permission bits, extended attributes, etc.) has changed. Note that although
|
|
|
|
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,
|
|
|
|
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
|
|
|
|
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
|
|
|
|
corresponds to the Tahoe file which is pointed at by the link. It means
|
|
|
@ -713,7 +713,6 @@ GET /uri/$DIRCAP/[SUBDIRS../]FILENAME?t=json
|
|
|
|
Windows) or file-contents-or-metadata-update-time of the local file (if
|
|
|
|
Windows) or file-contents-or-metadata-update-time of the local file (if
|
|
|
|
"tahoe backup" was run on a different operating system).
|
|
|
|
"tahoe backup" was run on a different operating system).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
=== Attaching an existing File or Directory by its read- or write- cap ===
|
|
|
|
=== Attaching an existing File or Directory by its read- or write- cap ===
|
|
|
|
|
|
|
|
|
|
|
|
PUT /uri/$DIRCAP/[SUBDIRS../]CHILDNAME?t=uri
|
|
|
|
PUT /uri/$DIRCAP/[SUBDIRS../]CHILDNAME?t=uri
|
|
|
@ -737,10 +736,15 @@ PUT /uri/$DIRCAP/[SUBDIRS../]CHILDNAME?t=uri
|
|
|
|
if there is already an object at the given location, rather than
|
|
|
|
if there is already an object at the given location, rather than
|
|
|
|
overwriting the existing object. To allow the operation to overwrite a
|
|
|
|
overwriting the existing object. To allow the operation to overwrite a
|
|
|
|
file, but return an error when trying to overwrite a directory, use
|
|
|
|
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
|
|
|
|
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
|
|
|
|
"false", "f", and "0" are synonyms for "False", and the parameter is
|
|
|
|
case-insensitive.
|
|
|
|
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 ===
|
|
|
|
=== Adding multiple files or directories to a parent directory at once ===
|
|
|
|
|
|
|
|
|
|
|
@ -802,7 +806,7 @@ DELETE /uri/$DIRCAP/[SUBDIRS../]CHILDNAME
|
|
|
|
The object will only become completely unreachable once 1: there are no
|
|
|
|
The object will only become completely unreachable once 1: there are no
|
|
|
|
reachable directories that reference it, and 2: nobody is holding a read-
|
|
|
|
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
|
|
|
|
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
|
|
|
|
This operation will not modify more than a single directory. Intermediate
|
|
|
|
directories which were implicitly created by PUT or POST methods will *not*
|
|
|
|
directories which were implicitly created by PUT or POST methods will *not*
|
|
|
@ -931,7 +935,7 @@ POST /uri/$DIRCAP/[SUBDIRS../]?t=mkdir&name=CHILDNAME
|
|
|
|
POST /uri?t=upload
|
|
|
|
POST /uri?t=upload
|
|
|
|
|
|
|
|
|
|
|
|
This uploads a file, and produces a file-cap for the contents, but does not
|
|
|
|
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.
|
|
|
|
this operation.
|
|
|
|
|
|
|
|
|
|
|
|
The file must be provided as the "file" field of an HTML encoded form body,
|
|
|
|
The file must be provided as the "file" field of an HTML encoded form body,
|
|
|
@ -1677,7 +1681,7 @@ GET / (introducer status)
|
|
|
|
|
|
|
|
|
|
|
|
== Static Files in /public_html ==
|
|
|
|
== 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
|
|
|
|
and serve it from a configurable directory which defaults to
|
|
|
|
$BASEDIR/public_html . This is configured by setting the "[node]web.static"
|
|
|
|
$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
|
|
|
|
value in $BASEDIR/tahoe.cfg . If this is left at the default value of
|
|
|
@ -1685,10 +1689,10 @@ 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 .
|
|
|
|
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
|
|
|
|
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
|
|
|
|
Summary: use explicit file- and dir- caps whenever possible, to reduce the
|
|
|
|
potential for surprises when the filesystem structure is changed.
|
|
|
|
potential for surprises when the filesystem structure is changed.
|
|
|
@ -1774,7 +1778,7 @@ Coordination Directive.
|
|
|
|
|
|
|
|
|
|
|
|
Tahoe nodes implement internal serialization to make sure that a single Tahoe
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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
|
|
|
|
Tahoe-1.1; back with Tahoe-1.0 the web client was responsible for serializing
|
|
|
|