From 7caec120b3c94bff24f495bddcd4473e5c5649bf Mon Sep 17 00:00:00 2001 From: nejucomo Date: Wed, 30 Jan 2008 01:27:42 -0700 Subject: [PATCH] docs: webapi: Add concise shorthand for options, input, output, and statuses to the operation descriptions... I'm not convinced if this is the best way to do this, but I find it handy to have a conscise "quick reference" for the webapi operations which summarize all related I/O. Another possibility is to reject this patch, but create a separate "webapi_quickref.html" with a concise table. --- docs/webapi.txt | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/docs/webapi.txt b/docs/webapi.txt index c4c3ab84..1affc843 100644 --- a/docs/webapi.txt +++ b/docs/webapi.txt @@ -94,6 +94,8 @@ d. examining files or directories GET $URL?t=json + out: json metadata + This returns machine-parseable information about the indicated file or directory in the HTTP response body. The JSON always contains a list, and the first element of the list is always a flag that indicates whether the @@ -132,6 +134,10 @@ e. downloading a file GET $URL + out: file contents or dir metadata + options: + save= - If true add header "Content-Disposition: attachment" + If the indicated object is a file, then this simply retrieves the contents of the file. The file's contents are provided in the body of the HTTP response. @@ -160,6 +166,9 @@ f. uploading a file PUT http://localhost:8123/uri + in: file contents + out: file write cap + Upload a file, returning its URI as the HTTP response body. This does not make the file visible from the virtual drive -- to do that, see section 1.h. below, or the convenience method in section 2.a.. @@ -168,6 +177,9 @@ g. creating a new directory PUT http://localhost:8123/uri?t=mkdir + in: (nothing) + out: directory write cap + Create a new empty directory and return its URI as the HTTP response body. This does not make the newly created directory visible from the virtual drive, but you can use section 1.h. to attach it, or the convenience method @@ -177,6 +189,11 @@ h. attaching a file or directory as the child of an extant directory PUT $URL?t=uri + in: child cap + out: the same child cap + options: + replace= - If true, overwrite existing contents. + This attaches a child (either a file or a directory) to the given directory $URL is required to indicate a directory as the second-to-last element and the desired filename as the last element, for example: @@ -191,7 +208,8 @@ h. attaching a file or directory as the child of an extant directory place, so we choose to use that particular directory to be the user's main directory.) - The URI of the child is provided in the body of the HTTP request. + The URI of the child is provided in the body of the HTTP request, + and this same URI is returned in the response body. There is an optional "?replace=" param whose value can be "true", "t", "1", "false", "f", or "0" (case-insensitive), and which defaults to "true". If @@ -230,6 +248,13 @@ a. uploading a file and attaching it to the vdrive PUT $URI + in: file contents + out: file write cap + + statuses: + 200 - File updated. [FIXME: Is this true yet?] + 201 - File created. [FIXME: Is this true yet?] + Upload a file and link it into the the vdrive at the location specified by $URI. The last item in the $URI must be a filename, and the second-to-last item must identify a directory. -- 2.45.2