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

docs/webapi.txt

@@ -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
+  If the given place in the vdrive contains a file, then this simply
-  vdrive. The Content-Type is set according to the vdrive's metadata (if
+  retrieves the contents of the file, exactly as described in the "GET URL"
-  available) or by using the usual filename-extension-magic built into most
+  paragraph of the "Files and Directories" section.  If the given place does
-  webservers. The file's contents are provided in the body of the HTTP
+  not contain a file then this returns an error. XYZ specify the error
-  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)
 
  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