mirror of
https://github.com/tahoe-lafs/tahoe-lafs.git
synced 2025-04-07 10:56:49 +00:00
webapi.txt: further refactoring and editing to clarify the fact that you don't know whether a thing is a file or a directory before you fetch it
This commit is contained in:
Zooko O'Whielacronx
parent
8b0807812b
commit
e68a0e07de
233
docs/webapi.txt
233
docs/webapi.txt
@ -1,16 +1,19 @@
|
||||
== connecting to the tahoe node ==
|
||||
|
||||
Writing "8011" into CLIENTDIR/webport causes the client to run a webserver on
|
||||
port 8011. Writing "tcp:8011:interface=127.0.0.1" into CLIENTDIR/webport does
|
||||
Writing "8011" into NODEDIR/webport causes the node to run a webserver on
|
||||
port 8011. Writing "tcp:8011:interface=127.0.0.1" into NODEDIR/webport does
|
||||
the same but binds to the loopback interface, ensuring that only the programs
|
||||
on the local host can connect. Using
|
||||
"ssl:8011:privateKey=mykey.pem:certKey=cert.pem" would run an SSL server. See
|
||||
twisted.application.strports for more details.
|
||||
|
||||
If CLIENTDIR/webpassword exists, it will be used (somehow) to require HTTP
|
||||
Digest Authentication for all webserver connections.
|
||||
If NODEDIR/webpassword exists, it will be used (somehow) to require HTTP
|
||||
Digest Authentication for all webserver connections. XXX specify how
|
||||
|
||||
|
||||
The client provides some small number of "virtual drives". In the 0.5
|
||||
== vdrive ==
|
||||
|
||||
The node 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.
|
||||
@ -27,34 +30,32 @@ contain the following directories and files:
|
||||
private/Pictures/tractors.jpg
|
||||
|
||||
|
||||
== vdrive ==
|
||||
|
||||
Within the webserver, there is a tree of resources. The top-level "vdrive"
|
||||
resource gives access to files and directories in all of the user's virtual
|
||||
drives. For example, the URL that corresponds to notes.txt would be:
|
||||
|
||||
FILEURL = http://localhost:8011/vdrive/global/Documents/notes.txt
|
||||
http://localhost:8011/vdrive/global/Documents/notes.txt
|
||||
|
||||
and the URL for tractors.jpg would be:
|
||||
|
||||
http://localhost:8011/vdrive/private/Pictures/tractors.jpg
|
||||
http://localhost:8011/vdrive/private/Pictures/tractors.jpg
|
||||
|
||||
In addition, each directory has a corresponding URL. The Pictures URL is:
|
||||
|
||||
DIRURL = http://localhost:8011/vdrive/private/Pictures
|
||||
http://localhost:8011/vdrive/private/Pictures
|
||||
|
||||
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, 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.
|
||||
In the following examples "$URL" is a shorthand for a URL like the ones
|
||||
described above. "$NEWURL" is a shorthand for a URL pointing to a location
|
||||
in the vdrive where currently nothing exists.
|
||||
|
||||
|
||||
=== Files and Directories ===
|
||||
=== files or directories ===
|
||||
|
||||
GET URL
|
||||
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
|
||||
@ -69,7 +70,7 @@ for files and directories which do not yet exist.
|
||||
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
|
||||
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
|
||||
@ -98,174 +99,150 @@ for files and directories which do not yet exist.
|
||||
corresponding FILEURL or DIRURL (except that dirnodes do not recurse --
|
||||
the "children" entry of the child is omitted).
|
||||
|
||||
DELETE $URL
|
||||
|
||||
=== Files ===
|
||||
This deletes the given file or directory from the vdrive. If it is a
|
||||
directory then this deletes all of its chilren. Note that this *does not*
|
||||
delete any parent directories, so a sequence of 'PUT NEWURL' and 'DELETE
|
||||
NEWURL' does not necessarily return the vdrive to its original state (it
|
||||
may leave some intermediate directory nodes).
|
||||
|
||||
GET FILEURL?t=file
|
||||
GET $URL?t=uri
|
||||
|
||||
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
|
||||
This returns the URI of the given file or directory in the HTTP response
|
||||
body. If you have read-write access to that resource then this returns a
|
||||
URI which provides read-write access. If you have read-only access to that
|
||||
resource then this returns a URI which provides read-only access.
|
||||
|
||||
PUT NEWFILEURL
|
||||
GET $URL?t=readonly-uri
|
||||
|
||||
This uploads a file to the given place in the vdrive. It will create
|
||||
intermediate directory nodes as necessary. The file's contents are taken
|
||||
from the body of the HTTP request. For convenience, the HTTP response
|
||||
contains the URI that results from uploading the file, although the client
|
||||
is not obligated to do anything with the URI. According to the HTTP/1.1
|
||||
specification (rfc2616), this should return a 200 (OK) code when modifying
|
||||
an existing file, and a 201 (Created) code when creating a new file.
|
||||
This returns the URI providing read-only access to the given file or
|
||||
directory (whether or not you have read-only or read-write access).
|
||||
(Currently all files are immutable so everyone has read-only access to all
|
||||
files.)
|
||||
|
||||
To use this, run 'curl -T localfile http://localhost:8011/vdrive/global/newfile'
|
||||
GET $URL?t=download&localfile=$LOCALPATH
|
||||
|
||||
DELETE FILEURL
|
||||
This instructs the node to download the given file or directory and write
|
||||
it into the local filesystem at $LOCALPATH. This request will only be
|
||||
accepted from an HTTP client connection originating at 127.0.0.1 . This
|
||||
request is most useful when the client node and the HTTP client are
|
||||
operated by the same user. $LOCALPATH should be an absolute pathname.
|
||||
|
||||
This deletes the given file from the vdrive. Note that this *does not*
|
||||
delete any parent directories, so a sequence of 'PUT NEWFILEURL' and
|
||||
'DELETE NEWFILEURL' does not necessarily return the vdrive to its original
|
||||
state (it may leave some intermediate directory nodes).
|
||||
PUT $NEWURL?t=upload&localfile=$LOCALPATH
|
||||
|
||||
GET FILEURL?t=download&localfile=$FILENAME
|
||||
This uploads a file or directory from the node's local filesystem to the
|
||||
vdrive. As with "GET $URL?t=download&localfile=$LOCALPATH", this request
|
||||
will only be accepted from an HTTP connection originating from 127.0.0.1.
|
||||
|
||||
This instructs the client to download the given file and write its contents
|
||||
into the local filesystem at $FILENAME. This request will only be accepted
|
||||
from an HTTP client connection originating at 127.0.0.1 . This request is
|
||||
most useful when the client node and the HTTP client are operated by the
|
||||
same user. $FILENAME should be an absolute pathname.
|
||||
If $LOCALPATH points to a directory on the node's local filesystem, then
|
||||
the node performs a recursive upload of the directory into the vdrive at
|
||||
the given location. $NEWURL will be created if necessary. When the
|
||||
operation is complete, the directory referenced by $NEWURL will contain all
|
||||
of the files and directories that were present in $LOCALPATH, so this is
|
||||
equivalent to the unix commands:
|
||||
|
||||
(thoughts: we could use either the response headers or the response body
|
||||
to indicate download progress)
|
||||
|
||||
PUT NEWFILEURL?t=upload&localfile=$FILENAME
|
||||
|
||||
This uploads file to the vdrive and gets the contents from a file in the
|
||||
client's local filesystem. As with GET, this request will only be accepted
|
||||
from an HTTP connection originating from 127.0.0.1.
|
||||
|
||||
(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.
|
||||
|
||||
GET FILEURL?t=readonly-uri
|
||||
|
||||
This also returns the URI of the given file. For now, all files are
|
||||
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?t=uri
|
||||
GET DIRURL?t=readonly-uri
|
||||
|
||||
Return a URI for this dirnode in the HTTP response body. If the dirnode is
|
||||
read-only, the t=uri and t=readonly-uri responses will be the same.
|
||||
|
||||
GET DIRURL?t=manifest
|
||||
|
||||
Return an HTML-formatted manifest of the given directory, for debugging.
|
||||
|
||||
PUT NEWDIRURL?t=mkdir
|
||||
|
||||
Create a new empty directory at the given path. The HTTP response contains
|
||||
the URI of the given directory, although the client is not obligated to do
|
||||
anything with it.
|
||||
|
||||
DELETE DIRURL
|
||||
|
||||
This deletes the given directory (and all of its children). Note that this
|
||||
*does not* delete any parent directories, so a sequence of 'PUT
|
||||
NEWDIRURL?t=mkdir' and 'DELETE NEWDIRURL does not necessarily return the
|
||||
vdrive to its original state (it may leave some intermediate directory
|
||||
nodes).
|
||||
|
||||
GET DIRURL?t=download&localdir=$DIRNAME
|
||||
|
||||
This instructs the client to perform a recursive download of the given
|
||||
directory and all its descendant files and directories, writing the results
|
||||
to the local filesystem starting at DIRNAME.
|
||||
|
||||
(thoughts: we could use the response headers or the response body to
|
||||
indicate download progress)
|
||||
|
||||
PUT NEWDIRURL?t=upload&localdir=$DIRNAME
|
||||
|
||||
This instructs the client to perform a recursive upload of a directory on
|
||||
the local filesystem into the vdrive at the given location. NEWDIRURL will
|
||||
be created if necessary. When the operation is complete, the directory
|
||||
referenced by NEWDIRURL will contain all of the files and directories that
|
||||
were present in DIRNAME, so this is equivalent to the unix commands:
|
||||
|
||||
mkdir -p NEWDIRURL; cp -r DIRNAME/* NEWDIRURL/
|
||||
mkdir -p $NEWURL; cp -r $LOCALPATH/* $NEWURL/
|
||||
|
||||
Note that the "curl" utility can be used to provoke this sort of recursive
|
||||
upload, since the -T option will make it use an HTTP 'PUT':
|
||||
|
||||
curl -T /dev/null 'http://localhost:8011/vdrive/global/newdir?t=upload&localdir=/home/user/directory-to-upload'
|
||||
|
||||
GET DIRURL?t=rename-form&name=$CHILDNAME
|
||||
|
||||
This provides a useful facility to browser-based user interfaces.
|
||||
It returns a page containing a form targetting the POST DIRURL t=rename
|
||||
functionality listed below, with the provided $CHILDNAME present in the
|
||||
|
||||
=== just for files ===
|
||||
|
||||
GET $URL?t=file
|
||||
|
||||
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 $NEWURL
|
||||
|
||||
This uploads a file to the given place in the vdrive. It will create
|
||||
intermediate directory nodes as necessary. The file's contents are taken
|
||||
from the body of the HTTP request. For convenience, the HTTP response
|
||||
contains the URI that results from uploading the file, although the node
|
||||
is not obligated to do anything with the URI. According to the HTTP/1.1
|
||||
specification (rfc2616), this should return a 200 (OK) code when modifying
|
||||
an existing file, and a 201 (Created) code when creating a new file.
|
||||
|
||||
To use this, run 'curl -T localfile http://localhost:8011/vdrive/global/newfile'
|
||||
|
||||
|
||||
=== just for directories ===
|
||||
|
||||
GET $URL?t=manifest
|
||||
|
||||
Return an HTML-formatted manifest of the given directory, for debugging.
|
||||
|
||||
PUT $NEWURL?t=mkdir
|
||||
|
||||
Create a new empty directory at the given path. The HTTP response contains
|
||||
the URI of the given directory, although the client is not obligated to do
|
||||
anything with it.
|
||||
|
||||
GET $URL?t=rename-form&name=$CHILDNAME
|
||||
|
||||
This provides a useful facility to browser-based user interfaces. It
|
||||
returns a page containing a form targetting the "POST $URL t=rename"
|
||||
functionality described below, with the provided $CHILDNAME present in the
|
||||
'from_name' field of that form. i.e. this presents a form offering to
|
||||
rename $CHILDNAME, requesting the new name, and submitting POST rename
|
||||
rename $CHILDNAME, requesting the new name, and submitting POST rename.
|
||||
|
||||
|
||||
== POST Forms ==
|
||||
== POST forms ==
|
||||
|
||||
POST DIRURL
|
||||
POST $URL
|
||||
t=upload
|
||||
name=childname (optional)
|
||||
file=newfile
|
||||
|
||||
This instructs the client to upload a file into the given dirnode. We need
|
||||
This instructs the node to upload a file into the given dirnode. We need
|
||||
this because forms are the only way for a web browser to upload a file
|
||||
(browsers do not know how to do PUT or DELETE). The file's contents and the
|
||||
new child name will be included in the form's arguments. This can only be
|
||||
used to upload a single file at a time. To avoid confusion, name= is not
|
||||
allowed to contain a slash (a 400 Bad Request error will result).
|
||||
|
||||
POST DIRURL
|
||||
POST $URL
|
||||
t=mkdir
|
||||
name=childname
|
||||
|
||||
This instructs the client to create a new empty directory. The name of the
|
||||
This instructs the node to create a new empty directory. The name of the
|
||||
new child directory will be included in the form's arguments.
|
||||
|
||||
POST DIRURL
|
||||
POST $URL
|
||||
t=uri
|
||||
name=childname
|
||||
uri=newuri
|
||||
|
||||
This instructs the client to attach a child that is referenced by URI (just
|
||||
like the PUT NEWFILEURL?t=uri method). The name and URI of the new child
|
||||
This instructs the node to attach a child that is referenced by URI (just
|
||||
like the PUT $URL?t=uri method). The name and URI of the new child
|
||||
will be included in the form's arguments.
|
||||
|
||||
POST DIRURL
|
||||
POST $URL
|
||||
t=delete
|
||||
name=childname
|
||||
|
||||
This instructs the client to delete a file from the given dirnode. The name
|
||||
This instructs the node to delete a file from the given dirnode. The name
|
||||
of the child to be deleted will be included in the form's arguments.
|
||||
|
||||
POST DIRURL
|
||||
POST $URL
|
||||
t=rename
|
||||
from_name=oldchildname
|
||||
to_name=newchildname
|
||||
|
||||
This instructs the client to rename a child within the given dirnode. The
|
||||
This instructs the node to rename a child within the given dirnode. The
|
||||
child specified by 'from_name' is removed, and reattached as a child named
|
||||
for 'to_name'. This is unconditional and will replace any child already
|
||||
present under 'to_name', akin to 'mv -f' in unix parlance.
|
||||
|
||||
|
||||
== URI ==
|
||||
== URIs ==
|
||||
|
||||
http://localhost:8011/uri/$URI
|
||||
|
||||
@ -300,7 +277,7 @@ 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
|
||||
PUT $URL?t=uri
|
||||
|
||||
This attaches a child (either a file or a directory) to the vdrive at the
|
||||
given location. The URI is provided in the body of the HTTP request. This
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user