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