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

webapi.txt: add "?t=file" flag and reorganize doc to discourage people from thinking that they know before hand the file-or-dir type of the thing that they are naming

Browse Source
This commit is contained in:
Zooko O'Whielacronx 2007-08-10 09:43:52 -07:00
parent 531109e803
commit 8b0807812b
1 changed files with 59 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

123
docs/webapi.txt
View File

@ -10,7 +10,7 @@ If CLIENTDIR/webpassword exists, it will be used (somehow) to require HTTP
Digest Authentication for all webserver connections.
The client provides some small number of "virtual drives". In the 0.4.0
The client provides some small number of "virtual drives". In the 0.5
release, this number is two: the first is the global shared vdrive, the
second is the private non-shared vdrive. We will call these "global" and
"private" for now.
@ -47,24 +47,66 @@ Now, what can we do with these URLs? By varying the HTTP "method"
(GET/PUT/POST/DELETE) and by appending a type-indicating query argument, we
control how what we want to do with the data and how it should be presented.
In the following examples, FILEURL and DIRURL are abbreviations for the
In the following examples, URL, FILEURL and DIRURL are abbreviations for the
previously listed examples. In addition. NEWFILEURL and NEWDIRURL are URLs
for files and directories which do not yet exist.
=== Files and Directories ===
GET URL
If the given place in the vdrive contains a file, then this simply
retrieves the contents of the file. The Content-Type is set according to
the vdrive's metadata (if available) or by using the usual
filename-extension-magic built into most webservers. The file's contents
are provided in the body of the HTTP response.
If the given place contains a directory, then this returns an HTML page,
intended to be used by humans, which contains HREF links to all files and
directories reachable from this dirnode. These HREF links do not have a t=
argument, meaning that a human who follows them will get pages also meant
for a human. It also contains forms to upload new files, and to delete
files and directories. These forms use POST methods to do their job.
GET URL?t=json
This returns machine-parseable information about the named file or
directory in the HTTP response body. This information contains a flag that
indicates whether the thing is a file or a directory.
If it is a file, then the information includes file size, metadata (like
Content-Type), and URIs, like this:
[ 'filenode', { 'mutable': bool, 'uri': file_uri, 'size': bytes } ]
If it is a directory, then it includes a flag to indicate whether this is a
read-write dirnode or a read-only dirnode, and information about the
children of this directory, as a mapping from child name to a set of
metadata about the child (the same data that would appear in a
corresponding GET?t=json of the child itself). Like this:
[ 'dirnode', { 'mutable': bool, 'uri': uri, 'children': children } ]
where 'children' is a dictionary in which the keys are child names
and the values depend upon whether the child is a file or a directory:
'foo.txt': [ 'filenode', { 'mutable': bool, 'uri': uri, 'size': bytes } ]
'subdir': [ 'dirnode', { 'mutable': bool, 'uri': uri } ]
note that the value is the same as the JSON representation of the
corresponding FILEURL or DIRURL (except that dirnodes do not recurse --
the "children" entry of the child is omitted).
=== Files ===
GET FILEURL
GET FILEURL?t=file
This simply retrives the contents of the file at the given place in the
vdrive. The Content-Type is set according to the vdrive's metadata (if
available) or by using the usual filename-extension-magic built into most
webservers. The file's contents are provided in the body of the HTTP
response.
(thought: we could conceivably provide some measure of gathering-peers
progress and pre-plaintext status information by emitting some extra
X-Tahoe-Status headers. Of course, once the headers are done and we start
sending plaintext, we have to stop sending such headers)
If the given place in the vdrive contains a file, then this simply
retrieves the contents of the file, exactly as described in the "GET URL"
paragraph of the "Files and Directories" section. If the given place does
not contain a file then this returns an error. XYZ specify the error
PUT NEWFILEURL
@ -85,19 +127,6 @@ for files and directories which do not yet exist.
'DELETE NEWFILEURL' does not necessarily return the vdrive to its original
state (it may leave some intermediate directory nodes).
GET FILEURL?t=json
This returns machine-parseable information about the file in the HTTP
response body, including file size, metadata (like Content-Type), and URIs.
This information is also required to contain a flag that distinguishes
between files and directories. Programatic clients are expected to use this
query before actually downloading the file's contents.
The JSON data is as follows:
[ 'filenode', { 'mutable': bool, 'uri': file_uri, 'size': bytes } ]
GET FILEURL?t=download&localfile=$FILENAME
This instructs the client to download the given file and write its contents
@ -118,7 +147,6 @@ for files and directories which do not yet exist.
(we could indicate upload progress too. The response body could contain
the URI of the uploaded file)
GET FILEURL?t=uri
This returns the URI of the given file in the HTTP response body.
@ -129,44 +157,9 @@ for files and directories which do not yet exist.
immutable, so t=uri and t=readonly-uri return the same value. In the
future, when we have mutable files, they will return different values.
=== Directories ===
GET DIRURL
This returns an HTML page, intended to be used by humans, which contains
HREF links to all files and directories reachable from this dirnode. These
HREF links do not have a t= argument, meaning that a human who follows them
will get pages also meant for a human. It also contains forms to upload new
files, and to delete files and directories. These forms use POST methods to
do their job.
GET DIRURL?t=json
This returns machine-parseable information about this directory in the HTTP
response body. This information first contains a flag to indicate that
DIRURL referenced a directory (as opposed to a file). Then it contains a
flag to indicate whether this is a read-write dirnode or a read-only
dirnode. Finally it also contains information about the children of this
directory, probably as a mapping from child name to a set of metadata about
the child (basically the same data that would appear in a corresponding
GET?t=json of the child itself). A programmatic client should be able to use
the information from this query to display filesystem navigation choices to
a human user.
The JSON data is as follows:
[ 'dirnode', { 'mutable': bool, 'uri': uri, 'children': children } ]
where 'children' is a dictionary in which the keys are child names
and the values depend upon whether the child is a file or a directory:
'foo.txt': [ 'filenode', { 'mutable': bool, 'uri': uri, 'size': bytes } ]
'subdir': [ 'dirnode', { 'mutable': bool, 'uri': uri } ]
note that the value is the same as the JSON representation of the
corresponding FILEURL or DIRURL (except that dirnodes do not recurse).
GET DIRURL?t=uri
GET DIRURL?t=readonly-uri
@ -223,6 +216,7 @@ for files and directories which do not yet exist.
'from_name' field of that form. i.e. this presents a form offering to
rename $CHILDNAME, requesting the new name, and submitting POST rename
== POST Forms ==
POST DIRURL
@ -270,6 +264,7 @@ for files and directories which do not yet exist.
for 'to_name'. This is unconditional and will replace any child already
present under 'to_name', akin to 'mv -f' in unix parlance.
== URI ==
http://localhost:8011/uri/$URI
@ -305,7 +300,6 @@ for files and directories which do not yet exist.
when URIs are used in this form, they must be specially quoted. All slashes
in the URI must be replaced by '!' characters.
PUT NEWFILEURL?t=uri
This attaches a child (either a file or a directory) to the vdrive at the
@ -328,6 +322,7 @@ for files and directories which do not yet exist.
redirection provided will escape the slashes with exclamation points, as
described above.
== XMLRPC ==
http://localhost:8011/xmlrpc