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 @@ + + + + + Ninja File IO Rest API Documentation.doc + + +

Cloud Status API

+ +

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.

+ +

File APIs

+ +

These APIs deal with single files. The shell will be limited to acting on files in paths the user has permissions to read/write. +

+ +

Create a new file

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

URL

http://someURL.com/file/<filepath>/<filename >

+ +

e.g.

+ +

+ http://someURL.com/file/c/users/jdoe/my%20documents/foo.html
http://someURL.com/file/users/jdoe/documents/foo.html
NOTE: all file paths are case sensitive
+

Method

POST

Request Headers

none

Request Body

Optional
Raw file contents with the appropriate content-type.
If the body is empty, the file will be created with no content.
+

Response headers

Cache-Control: no-cache

Response body

none

Return Status Codes

201 “Created” – + File was created
400 “Bad Request” – the file was not able to be created because it exists already.
500 “Internal Server Error” – + the file was not able to be created.

+

Update an existing file (save over existing file)

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

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

Returns Status Codes

204 “No Content” – + File was saved
404 “Not found” – + the file at the indicated URI does not exist.
500 “Internal Server Error” – the file was not able to be saved.
+

+

Copy, Move of an existing file

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

URL

+ http://someURL.com/file/<filepath>/<filename >

Method

PUT

Request Headers

Required
sourceURI
value= <source file path in same format as in the URL>
e.g. c/users/jdoe/my%20documents/foo.html
+

+ +

Optional
overwrite-destination
value=true/false
default=false
true indicates that it is safe to overwrite the destination file if it exists
+

+ +

delete-source
value: true/false
default: false
true means to remove he source after the copy operation succeeds.
+

Request Body

None

Response Headers

Cache-Control: no-cache

Response Body

None

Return Status Codes

204 “No Content” – The operation succeeded
404 “Not found” – + the source file at the indicated URI does not exist.
500 “Internal Server Error” – the file operation was not able to be completed.
+

+

Delete an existing file

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

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
404 “Not found” – the file at the indicated URI does not exist.
500 “Internal Server Error” – + the file was not able to be deleted.

Notes

This will only delete a single file. You cannot pass wildcard characters in the path. +

+

Read an existing file

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

URL

+ http://someURL.com/file/<filepath>/<filename >

Method

GET

Request Headers

check-existence-only
value=true/false
default none
if true, no content is returned. The return status code indicates if the directory exists or not.
+

+ +

If-modified-since
value=<ms since 1/1/1970 in GMT>. If this header is present, the server will determine if the file has been modified since the time specified. If the modified date is later than the value of “if-modified-since”, then the server will return 200. If not 304 is returned. check-existence-only is ignored when this header is specified.
+

+ +

get-file-info
If specified, this will cause this api to return a JSON string containing the creation and modification times in ms since 1/1/1970, the file size in bytes and a boolean indicating if the file is read only.
+

+ +

Example,

+ +

{
   "creationDate": "2133456525488",
   "modifiedDate": "2133456525488",
   "size": "2125",
   "readOnly": "true"
}
+

+ +

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.

204 “No Content” – + The file exists and no content was returned because the “check-existence-only” or
“get-file-info” header was set to true. 304 “Not modified” + - returned when a file modification check was made and the file was not modified after the time specified in the “if-modified-since” + header.

404 “Not found” – the file at the indicated URI does not exist.
+

+

+ +

+
+

Directory APIs

+ +

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. +

+ +

Create a new directory

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

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
400 “Bad Request” – + the directory was not able to be 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”. +

+

+ +

Delete an existing directory

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

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
404 “Not found” – the directory at the indicated URI does not exist.
500 “Internal Server Error” – + the directory was not able to be deleted.

Notes

+

+ +

List the contents of an existing directory

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

URL

http://someURL.com/directory/<directory path>

+

Method

GET

Request Headers

Required

+ +

recursive
value=true/false
default=false
if set to true this call will get the contents of every sub-directory recursively, except if return-type is set to “files”, then only the files in the top level directory are returned.

file-filters
specifies the filters to use for files that are returned. Only those matching one of the filters listed will be returned. The default is an empty string meaning all files are returned. Do not include * as an filter. To not filter by extension either do not set this header or pass an empty string.
value=<semi-colon delimited filter list>
e.g. “xml;html”

return-type
value=”directories”, “files”, “all”
default=”all”
“directories” – + only subdirectories of the URI will be returned
“files” – only files within the directory will be returned
“all” – + both subdirectories and files will be returned

check-existence-only
value=true/false
default false
if true, no content is returned. The return status code indicates if the directory exists or not. “recursive” + and “return-type” are ignored if this header is set to true.

+ +

If-modified-since
value=<ms since 1/1/1970 in GMT>. If this header is present, the server will compare the modification times of the folder AND its contents (recursively if “recursive” + is true) against the specified date. If any folder/file has a modified date later than the value of “if-modified-since”, then the server will return 200. If no file/folder was modified after that time then 304 is returned. check-existence-only is ignored when this header is specified.
+

+ +

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”,
        “size”:”21335”,
        “writable”:”true”,
+

+ +

         "children":[

+ +

            {

+ +

"type": “directory”

+ +

               "name":"anotherDir", +

+ +

               "uri":"c:/my documents/subDirectory/anotherDir", +

+ +

               “size”:”33225”,
              “writable”:”true”,
+

+ +

               "children":null +

+ +

            },

+ +

            {

+ +

               "type": “directory”, +

+ +

"name":"anEmptySubdirectory",

+ +

               "uri":"c:/my documents/subDirectory/anEmptySubdirectory" +

+ +

               “creationDate”:”2133456525488”, +

+ +

               “modifiedDate”:”2133456525488”, +

+ +

               “size”:”2125”,
              “writable”:”true”,
+

+ +

            },

+ +

            {

+ +

               "type": “file”, +

+ +

"name":"aFile.txt",

+ +

               "uri":"c:/my documents/subDirectory/aFile.txt", +

+ +

               “creationDate”:”2133456525488”, +

+ +

               “modifiedDate”:”2133456525488”, +

+ +

               “size”:”2125”,
              “writable”:”true”,
+

+ +

            }

+ +

         ]

+ +

      },

+ +

      {

+ +

         “type”:"file",

+ +

         "name":"someFile.html",

+ +

         "uri":"c:/my documents/someFile.html", +

+ +

         “creationDate”:”2133456525488”, +

+ +

         “modifiedDate”:”2133456525488”, +

+ +

          “size”:”6652”,
        “writable”:”false”,
+

+ +

      }

+ +

   ]

+ +

}

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.
204 “No Content” – + The directory exists and no content was returned because the “check-existence-only” header was set to true

304 “Not modified” + - returned when a folder modification check was made and no contents were modified after the time specified in the “if-modified-since” + header.

404 “Not found” – the directory at the indicated URI does not exist.

413 “Request entity too large” + - the request timed out. This can happen if the request is taking too long to process when doing a recursive query.
+

+


Copy, Move of an existing directory

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

URL

http://someURL.com/directory/<directory path>

+

Method

PUT

Request Headers

Required

+ +

sourceURI
value= <source directory path in same format as in the URL>
+

+ +

operation
value=”copy” or “move”
+

+ +

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
404 “Not found” – + the source file at the indicated URI does not exist.
400-“Bad Request” – if the operation value is invalid or if the destination directory
500 “Internal Server Error” – + the file operation was not able to be completed.

+ +

Web API

+

This API is used to request file data from a URL.

+

Get text or binary data from a URL

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

URL

http://someURL.com/web?url=http://foo.com/bar.txt

+

Method

GET

Request Headers

Required

+

return-type
value=”text” or “binary”
default=“text“

+

Request Body

None

Response Headers

Cache-Control: no-cache

Response Body

None

Return Status Codes

200 “OK” – The operation succeeded
404 “Not found” – + the source file at the indicated URI does not exist.
501-“Not Implemented” – if any method other than GET is used

+ +

Cloud Status API

+

This API is used to request cloud status information.

+

Get the cloud status JSON

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

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

+ + \ No newline at end of file -- cgit v1.2.3