From c5a9744b87354f67e219ee0069180a94ed27c3ee Mon Sep 17 00:00:00 2001 From: Pacien TRAN-GIRARD Date: Sat, 8 Sep 2012 14:02:56 +0200 Subject: First draft: program structure. --- File IO REST API Spec.html | 881 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 881 insertions(+) create mode 100644 File IO REST API Spec.html (limited to 'File IO REST API Spec.html') diff --git a/File IO REST API Spec.html b/File IO REST API Spec.html new file mode 100644 index 0000000..289359e --- /dev/null +++ b/File IO REST API Spec.html @@ -0,0 +1,881 @@ + + + +
+In order to determine if the ninja cloud is running for a particular server (local or remote), you can call +
+ +http://<the server url>/cloudstatus
+ +if the cloud server is up and running it will return status code 200 and a json string as follows: +
+ +{"name":"Ninja Local Cloud","status": "running","server-root":"C:/Users/vpn847/Documents/Ninja Projects","version":"0.5.0.0"} +
+ ++ +
The cloud name provides a user facing name for the particular cloud server.
+ +These APIs deal with single files. The shell will be limited to acting on files in paths the user has permissions to read/write. +
+ +URL |
+ http://someURL.com/file/<filepath>/<filename > + +e.g. + +
+ http://someURL.com/file/c/users/jdoe/my%20documents/foo.html |
+
Method |
+ POST |
+
Request Headers |
+ none |
+
Request Body |
+ Optional |
+
Response headers |
+ Cache-Control: no-cache |
+
Response body |
+ none |
+
Return Status Codes |
+ 201 “Created” –
+ File was created |
+
URL |
+ + http://someURL.com/file/<filepath>/<filename > |
+
Method |
+ PUT |
+
Request Headers |
+ none |
+
Request Body |
+ Raw file contents with the appropriate content-type. |
+
Response Headers |
+ Cache-Control: no-cache |
+
Response Body |
+ None |
+
+ | 204 “No Content” –
+ File was saved |
+
URL |
+ + http://someURL.com/file/<filepath>/<filename > |
+
Method |
+ PUT |
+
Request Headers |
+ Required Optional delete-source |
+
Request Body |
+ None |
+
Response Headers |
+ Cache-Control: no-cache |
+
Response Body |
+ None |
+
Return Status Codes |
+ 204 “No Content” – The operation succeeded |
+
URL |
+ + http://someURL.com/file/<filepath>/<filename > |
+
Method |
+ DELETE |
+
Request Headers |
+ none |
+
Request Body |
+ None |
+
Response Headers |
+ Cache-Control: no-cache |
+
Response Body |
+ None |
+
Return Status Codes |
+ 204 “No Content” –
+ File was successfully removed |
+
Notes |
+ This will only delete a single file. You cannot pass wildcard characters in the path. + |
+
URL |
+ + http://someURL.com/file/<filepath>/<filename > |
+
Method |
+ GET |
+
Request Headers |
+ check-existence-only If-modified-since get-file-info Example, + +{ All three of the above headers are mutually exclusive. Only one can be specified at a time. + + + |
+
Request Body |
+ None |
+
Response Headers |
+ Content-Type: <string> + +Cache-Control: no-cache |
+
Response Body |
+ Raw file data |
+
Return Status Codes |
+ 200 “OK” – The file exists and was successfully read and the contents returned with the content type. When a time is specified with the “if-modified-since”
+ header and a file was modified after that date, a return of 200 indicates that there was a change. |
+
+ +
+ +
These APIs operate on directories. The path parameter must be to a directory and not a specific file. The path parameter cannot contain wildcard characters. +
+ +URL |
+ http://someURL.com/directory/<directory path> + |
+
Method |
+ POST |
+
Request Headers |
+ none |
+
Request Body |
+ None |
+
Response headers |
+ Cache-Control: no-cache |
+
Response body |
+ None |
+
Return Status Codes |
+ 201 “Created” – The directory was created |
+
Notes: |
+ This will create the entire path. E.g. passing c:\foo\bar where there is no existing c:\foo directory will cause a directory “foo” + to be created under c:\ as well as a subdirectory named “bar” under “foo”. + |
+
+ +
URL |
+ http://someURL.com/directory/<directory path> + |
+
Method |
+ DELETE |
+
Request Headers |
+ none |
+
Request Body |
+ None |
+
Response Headers |
+ Cache-Control: no-cache |
+
Response Body |
+ None |
+
Return Status Codes |
+ 204 “No Content” –
+ The directory was successfully removed |
+
Notes |
+
+ +
URL |
+ http://someURL.com/directory/<directory path> + |
+
Method |
+ GET |
+
Request Headers |
+ Required + +recursive If-modified-since NOTE: If the path is empty, then all parameters are ignored and the API returns all top level disks and or folders available to the user. + + +TBD for cloud: may need to include credentials and user account info |
+
Request Body |
+ None |
+
Response Headers |
+ Content-Type: application/json + +Cache-Control: no-cache |
+
Response Body |
+ JSON listing the directory contents. + +Example: + +the json below represents the response for a listing of the “c:/my documents” + directory + +The type property of the object can be used to differentiate between files and directories. Both files and directories also contain a name, uri property as well as a creationDate and modifiedDate. The dates are all in milliseconds since UNIX epoch. Directories also contain a children property. If the children property is an empty array it means that the directory has no contents. If the children property is defined but null, that means the directory does have content but that content has not yet been retrieved. Another XHR must be called to obtain its contents. If the children property is an array with a size > 0, then it contains the contents of the directory. + + ++ + { + +"type": “directory”, + +"name": "my documents", + +"uri": "c:/my documents/", + +"children":[ + +{ + +"type": “directory”, + +"name":"subDirectory", + +"uri":"c:/my documents/subDirectory", + + +“creationDate”:”2133456525488”, + + + “modifiedDate”:”2133456525488”, "children":[ + +{ + +"type": “directory” + +"name":"anotherDir", + + +"uri":"c:/my documents/subDirectory/anotherDir", + + + “size”:”33225”, "children":null + + +}, + +{ + +"type": “directory”, + + +"name":"anEmptySubdirectory", + +"uri":"c:/my documents/subDirectory/anEmptySubdirectory" + + +“creationDate”:”2133456525488”, + + +“modifiedDate”:”2133456525488”, + + + “size”:”2125”, }, + +{ + +"type": “file”, + + +"name":"aFile.txt", + +"uri":"c:/my documents/subDirectory/aFile.txt", + + +“creationDate”:”2133456525488”, + + +“modifiedDate”:”2133456525488”, + + + “size”:”2125”, } + +] + +}, + +{ + +“type”:"file", + +"name":"someFile.html", + +"uri":"c:/my documents/someFile.html", + + +“creationDate”:”2133456525488”, + + +“modifiedDate”:”2133456525488”, + + + “size”:”6652”, } + +] + +} |
+
Return Status Codes |
+ 200 “OK” – The directory exists and its contents were successfully read and the returned in the response body. When a time is specified with the “if-modified-since”
+ header and a file/folder was modified after that date, a return of 200 indicates that there was a change. |
+
URL |
+ http://someURL.com/directory/<directory path> + |
+
Method |
+ PUT |
+
Request Headers |
+ Required + +sourceURI operation NOTE: the destination directory must not exist. + +TBD for cloud: may need to include credentials and user account info |
+
Request Body |
+ None |
+
Response Headers |
+ Cache-Control: no-cache |
+
Response Body |
+ None |
+
Return Status Codes |
+ 204 “No Content” – The operation succeeded |
+
This API is used to request file data from a URL.
+URL |
+ http://someURL.com/web?url=http://foo.com/bar.txt + |
+
Method |
+ GET |
+
Request Headers |
+ Required +return-type |
Request Body |
+ None |
+
Response Headers |
+ Cache-Control: no-cache |
+
Response Body |
+ None |
+
Return Status Codes |
+ 200 “OK” – The operation succeeded |
+
This API is used to request cloud status information.
+URL |
+ http://someURL.com/cloudstatus + |
+
Method |
+ GET |
+
Request Headers |
+ None |
+
Request Body |
+ None |
+
Response Headers |
+ Cache-Control: no-cache |
+
Response Body |
+ JSON string containg the cloud status |
+
Return Status Codes |
+ 200 “OK” – The operation succeeded |
+