Minor improvements to webapi.rst.

[tahoe-lafs/tahoe-lafs.git] / docs / frontends / webapi.rst

diff --git a/docs/frontends/webapi.rst b/docs/frontends/webapi.rst
index 433cd7a370c896c29fd72e48efb883073c3382ea..9072ef2896eaebb9d275b0a5692778bd7ba32780 100644 (file)
--- a/docs/frontends/webapi.rst
+++ b/docs/frontends/webapi.rst
@@ -29,7 +29,7 @@ The Tahoe REST-ful Web API
     6.  `Attaching an Existing File Or Directory (by URI)`_
     7.  `Unlinking a Child`_
     8.  `Renaming a Child`_
-    9.  `Moving a Child`_
+    9.  `Relinking ("Moving") a Child`_
     10. `Other Utilities`_
     11. `Debugging and Testing Features`_
 
@@ -157,9 +157,7 @@ listening on this port::
 
  http://127.0.0.1:3456/uri/ + $CAP
 
-So, to access the directory named above (which happens to be the
-publically-writeable sample directory on the Tahoe test grid, described at
-http://allmydata.org/trac/tahoe-lafs/wiki/TestGrid), the URL would be::
+So, to access the directory named above, the URL would be::
 
  http://127.0.0.1:3456/uri/URI%3ADIR2%3Adjrdkfawoqihigoett4g6auz6a%3Ajx5mplfpwexnoqff7y5e4zjus4lidm76dcuarpct7cckorh2dpgq/
 
@@ -1250,7 +1248,7 @@ Unlinking a Child
 
 ``POST /uri/$DIRCAP/[SUBDIRS../]?t=delete&name=CHILDNAME``
 
-``POST /uri/$DIRCAP/[SUBDIRS../]?t=unlink&name=CHILDNAME``
+``POST /uri/$DIRCAP/[SUBDIRS../]?t=unlink&name=CHILDNAME``    (Tahoe >= v1.9)
 
  This instructs the node to remove a child object (file or subdirectory) from
  the given directory, which must be mutable. Note that the entire subtree is
@@ -1287,20 +1285,24 @@ Renaming a Child
  for "False"; and the parameter is case-insensitive.
 
 
-Moving a Child
---------------
+Relinking ("Moving") a Child
+----------------------------
 
 ``POST /uri/$DIRCAP/[SUBDIRS../]?t=relink&from_name=OLD&to_dir=$NEWDIRCAP/[NEWSUBDIRS../]&to_name=NEW``
  ``[&replace=true|false|only-files]``    (Tahoe >= v1.10)
 
- This instructs the node to move a child of the given source directory,
- into a different directory and/or to a different name. The command is
- named ``relink`` because it works by adding a new link from the new
- location, then removing the old link. The source and destination
- directories must be writeable. If {{{to_dir}}} is not present, the child
- link is renamed within the same directory. If {{{to_name}}} is not present
- then it defaults to {{{from_name}}}. If the destination link (directory
- and name) is the same as the source link, the operation has no effect.
+ This instructs the node to move a child of the given source directory, into
+ a different directory and/or to a different name. The command is named
+ ``relink`` because what it does is add a new link to the child from the new
+ location, then remove the old link. Nothing is actually "moved": the child
+ is still reachable through any path from which it was formerly reachable,
+ and the storage space occupied by its ciphertext is not affected.
+
+ The source and destination directories must be writeable. If {{{to_dir}}} is
+ not present, the child link is renamed within the same directory. If
+ {{{to_name}}} is not present then it defaults to {{{from_name}}}. If the
+ destination link (directory and name) is the same as the source link, the
+ operation has no effect.
 
  Metadata from the source directory entry is preserved. Multiple levels of
  descent in the source and destination paths are supported.
@@ -1409,12 +1411,16 @@ mainly intended for developers.
     count-shares-good: the number of good shares that were found
     count-shares-needed: 'k', the number of shares required for recovery
     count-shares-expected: 'N', the number of total shares generated
-    count-good-share-hosts: the number of distinct storage servers with good
-                            shares
+    count-good-share-hosts: the number of distinct storage servers with
+                            good shares. Note that a high value does not
+                            necessarily imply good share distribution,
+                            because some of these servers may only hold
+                            duplicate shares.
     count-wrong-shares: for mutable files, the number of shares for
                         versions other than the 'best' one (highest
                         sequence number, highest roothash). These are
-                        either old ...
+                        either old, or created by an uncoordinated or
+                        not fully successful write.
     count-recoverable-versions: for mutable files, the number of
                                 recoverable versions of the file. For
                                 a healthy file, this will equal 1.