Changes in docs/frontends/webapi.rst [b7e76c7:705dc85] in trunk
- File:
-
- 1 edited
-
docs/frontends/webapi.rst (modified) (18 diffs)
Legend:
- Unmodified
- Added
- Removed
-
TabularUnified docs/frontends/webapi.rst ¶
rb7e76c7 r705dc85 72 72 ====================================== 73 73 74 As described in :doc:`../architecture`, each file and directory in a Tahoe75 virtual filesystemis referenced by an identifier that combines the74 As described in :doc:`../architecture`, each file and directory in a 75 Tahoe-LAFS file store is referenced by an identifier that combines the 76 76 designation of the object with the authority to do something with it (such as 77 77 read or modify the contents). This identifier is called a "read-cap" or … … 94 94 operations are required to have no side-effects. 95 95 96 PUT is used to upload new objects into the file system, or to replace an96 PUT is used to upload new objects into the file store, or to replace an 97 97 existing link or the contents of a mutable file. DELETE is used to unlink 98 98 objects from directories. Both PUT and DELETE are required to be idempotent: … … 108 108 also be done with a POST. 109 109 110 Tahoe 's web API is designed for two different kinds of consumer. The first is111 a program that needs to manipulate the virtual file system. Such programs are110 Tahoe-LAFS' web API is designed for two different kinds of consumer. The 111 first is a program that needs to manipulate the file store. Such programs are 112 112 expected to use the RESTful interface described above. The second is a human 113 using a standard web browser to work with the file system. This user is given114 a series of HTML pages with links to download files, and forms that use POST 115 actions to upload, rename, and unlink files.113 using a standard web browser to work with the file store. This user is 114 presented with a series of HTML pages with links to download files, and forms 115 that use POST actions to upload, rename, and unlink files. 116 116 117 117 When an error occurs, the HTTP response code will be set to an appropriate … … 333 333 334 334 Now that we know how to build URLs that refer to files and directories in a 335 Tahoe virtual filesystem, what sorts of operations can we do with those URLs?335 Tahoe-LAFS file store, what sorts of operations can we do with those URLs? 336 336 This section contains a catalog of GET, PUT, DELETE, and POST operations that 337 337 can be performed on these URLs. This set of operations are aimed at programs … … 420 420 421 421 This uploads a file, and produces a file-cap for the contents, but does not 422 attach the file into the file system. No directories will be modified by422 attach the file into the file store. No directories will be modified by 423 423 this operation. The file-cap is returned as the body of the HTTP response. 424 424 … … 436 436 Create a new empty directory and return its write-cap as the HTTP response 437 437 body. This does not make the newly created directory visible from the 438 file system. The "PUT" operation is provided for backwards compatibility:438 file store. The "PUT" operation is provided for backwards compatibility: 439 439 new code should use POST. 440 440 … … 808 808 under that name. 809 809 810 Note however, that if the edge in the Tahoe filesystem points to a mutable811 file and the contents of that mutable file is changed, then the810 Note however, that if the edge in the Tahoe-LAFS file store points to a 811 mutable file and the contents of that mutable file is changed, then the 812 812 'tahoe':'linkmotime' value on that edge will *not* be updated, since the 813 813 edge itself wasn't updated -- only the mutable file was. … … 836 836 "tahoe backup" command (in Tahoe v1.3.0 and later) to set the 'mtime' and 837 837 'ctime' values when backing up files from a local filesystem into the 838 Tahoe filesystem. As of Tahoe v1.4.0, the set_children API cannot be used839 to set anything under the 'tahoe' key of the metadata dict -- if you838 Tahoe-LAFS file store. As of Tahoe v1.4.0, the set_children API cannot be 839 used to set anything under the 'tahoe' key of the metadata dict -- if you 840 840 include 'tahoe' keys in your 'metadata' arguments then it will silently 841 841 ignore those keys. … … 865 865 866 866 1. You might be confused about whether it reflects the time of the creation 867 of a link in the Tahoe filesystem (by a version of Tahoe < v1.7.0) or a868 timestamp copied in by "tahoe backup" from a local filesystem.867 of a link in the Tahoe-LAFS file store (by a version of Tahoe < v1.7.0) 868 or a timestamp copied in by "tahoe backup" from a local filesystem. 869 869 870 870 2. You might be confused about whether it is a copy of the file creation … … 896 896 897 897 This attaches a child object (either a file or directory) to a specified 898 location in the virtual filesystem. The child object is referenced by its898 location in the Tahoe-LAFS file store. The child object is referenced by its 899 899 read- or write- cap, as provided in the HTTP request body. This will create 900 900 intermediate directories as necessary. … … 1009 1009 This section describes the HTTP operations that provide support for humans 1010 1010 running a web browser. Most of these operations use HTML forms that use POST 1011 to drive the Tahoe node. This section is intended for HTML authors who want1012 to write web pages that contain forms and buttons which manipulate the Tahoe1013 filesystem.1011 to drive the Tahoe-LAFS node. This section is intended for HTML authors who 1012 want to write web pages containing user interfaces for manipulating the 1013 Tahoe-LAFS file store. 1014 1014 1015 1015 Note that for all POST operations, the arguments listed can be provided … … 1108 1108 ``POST /uri?t=mkdir`` 1109 1109 1110 This creates a new empty directory, but does not attach it to the virtual1111 filesystem.1110 This creates a new empty directory, but does not attach it to any other 1111 directory in the Tahoe-LAFS file store. 1112 1112 1113 1113 If a "redirect_to_result=true" argument is provided, then the HTTP response … … 1151 1151 1152 1152 This uploads a file, and produces a file-cap for the contents, but does not 1153 attach the file into the filesystem. No directories will be modified by1154 this operation.1153 attach the file to any directory in the Tahoe-LAFS file store. That is, no 1154 directories will be modified by this operation. 1155 1155 1156 1156 The file must be provided as the "file" field of an HTML encoded form body, … … 1700 1700 reachable from the starting directory. The path will be slash-joined, and 1701 1701 the filecap/dircap will contain a link to the object in question. This page 1702 gives immediate access to every object in the virtual filesystemsubtree.1702 gives immediate access to every object in the file store subtree. 1703 1703 1704 1704 This operation uses the same ophandle= mechanism as deep-check. The … … 1834 1834 1835 1835 The portion of the web namespace that begins with "/uri" (and "/named") is 1836 dedicated to giving users (both humans and programs) access to the Tahoe 1837 virtual filesystem. The rest of the namespace provides status information 1838 about the state of the Tahoenode.1836 dedicated to giving users (both humans and programs) access to the Tahoe-LAFS 1837 file store. The rest of the namespace provides status information about the 1838 state of the Tahoe-LAFS node. 1839 1839 1840 1840 ``GET /`` (the root page) … … 1844 1844 Node information: library versions, local nodeid, services being provided. 1845 1845 1846 File system Access Forms: create a new directory, view a file/directory by1846 File store access forms: create a new directory, view a file/directory by 1847 1847 URI, upload a file (unlinked), download a file by 1848 1848 URI. 1849 1849 1850 Grid Status: introducer information, helper information, connected storage1850 Grid status: introducer information, helper information, connected storage 1851 1851 servers. 1852 1852 … … 1995 1995 1996 1996 Summary: use explicit file- and dir- caps whenever possible, to reduce the 1997 potential for surprises when the filesystem structure is changed. 1998 1999 Tahoe provides a mutable filesystem, but the ways that the filesystem can 2000 change are limited. The only thing that can change is that the mapping from 2001 child names to child objects that each directory contains can be changed by 2002 adding a new child name pointing to an object, removing an existing child name, 2003 or changing an existing child name to point to a different object. 2004 2005 Obviously if you query Tahoe for information about the filesystem and then act 2006 to change the filesystem (such as by getting a listing of the contents of a 2007 directory and then adding a file to the directory), then the filesystem might 2008 have been changed after you queried it and before you acted upon it. However, 2009 if you use the URI instead of the pathname of an object when you act upon the 2010 object, then the only change that can happen is if the object is a directory 2011 then the set of child names it has might be different. If, on the other hand, 2012 you act upon the object using its pathname, then a different object might be in 2013 that place, which can result in more kinds of surprises. 1997 potential for surprises when the file store structure is changed. 1998 1999 Tahoe-LAFS provides a mutable file store, but the ways that the store can 2000 change are limited. The only things that can change are: 2001 * the mapping from child names to child objects inside mutable directories 2002 (by adding a new child, removing an existing child, or changing an 2003 existing child to point to a different object) 2004 * the contents of mutable files 2005 2006 Obviously if you query for information about the file store and then act 2007 to change it (such as by getting a listing of the contents of a mutable 2008 directory and then adding a file to the directory), then the store might 2009 have been changed after you queried it and before you acted upon it. 2010 However, if you use the URI instead of the pathname of an object when you 2011 act upon the object, then it will be the same object; only its contents 2012 can change (if it is mutable). If, on the other hand, you act upon the 2013 object using its pathname, then a different object might be in that place, 2014 which can result in more kinds of surprises. 2014 2015 2015 2016 For example, suppose you are writing code which recursively downloads the … … 2019 2020 then it recurses into that directory. Now, if the download and the recurse 2020 2021 actions are performed using the child's name, then the results might be 2021 wrong, because for example a child name that pointed to a sub -directory when2022 wrong, because for example a child name that pointed to a subdirectory when 2022 2023 you listed the directory might have been changed to point to a file (in which 2023 case your attempt to recurse into it would result in an error and the file 2024 would be skipped), or a child name that pointed to a file when you listed the 2025 directory might now point to a sub-directory (in which case your attempt to 2026 download the child would result in a file containing HTML text describing the 2027 sub-directory!). 2028 2029 If your recursive algorithm uses the uri of the child instead of the name of 2024 case your attempt to recurse into it would result in an error), or a child 2025 name that pointed to a file when you listed the directory might now point to 2026 a subdirectory (in which case your attempt to download the child would result 2027 in a file containing HTML text describing the subdirectory!). 2028 2029 If your recursive algorithm uses the URI of the child instead of the name of 2030 2030 the child, then those kinds of mistakes just can't happen. Note that both the 2031 2031 child's name and the child's URI are included in the results of listing the
Note: See TracChangeset
for help on using the changeset viewer.
