API Spec

#Filemanager-2.0 API Spec

FM2 will base it's api on the JSON API 1.0 spec located at JSON API Currently, the api closely resembles the original connector, so moving to this spec is a work in progress.

The ui will have an api endpoint defined in the fm2.ui.config.json file under config.options.apiEndpoint, it is currently named config.options.fileConnector. This endpoint will point to an api with the following format.

##Endpoints
#####"/" Filemanager itself
#####"/item" A specific item
#####"/item/preview" A specific items preview and/or thumbnail
#####"/item/meta" Meta information about a specific item
#####"/file" A specific file
#####"/folder" A specific folder

##Verb Mapping
We will use the following mapping for verbs to routes.

• GET get the object
• POST save a new object
• PUT replace an object
• PATCH move an object
• DELETE delete an object

##"/"

GET*

• Retrieve the server's rules(allowed filetypes, etc)

##"/item"

GET ?path=/path/file.ext || path=/folder

• Download the specific file or a zip of the folder
• Example: http://api.com:3000/filemanager/item?path=/path/file.ext

PATCH ?path=/folder/file.ext || path=/folder &newPath=/newFolder

• Move the item to the new path
• Example: http://api.com:3000/filemanager/item?path=/folder/file.ext&newPath=/newFolder

DELETE ?path=/path/file.txt || path=/folder

• Delete the item
• Example: http://api.com:3000/filemanager/item?path=/folder/file.ext

##"/item/preview"

GET ?path=/path/file.ext || path=/folder

• Download the specific file or folders preview
• Example: http://api.com:3000/filemanager/item/preview?path=/path/file.ext

##"/item/meta"

GET ?path=/folder/file.ext || path=/folder

• Get the meta information for that item, be it a file or a folder
• Example: http://api.com:3000/filemanager/item/meta?path=/folder

##"/item/meta/name"

PUT ?path=/folder/file.ext || path=/folder &new=myNewName.ext

• Replace/update the name of the item
• Example: http://api.com:3000/filemanager/item/meta/name?path=/folder/file.ext&new=newfilename.ext

##"/file"

POST {"path": "/folder/file.ext"}

• Save a new file
• File node is named "file"
• Example: http://api.com:3000/filemanager/file {"path": "/folder/file.ext"}

PUT &path=/folder/file.ext

• replace the file
• Example: http://api.com:3000/filemanager/file?path=/folder/file.ext

##"/folder"

####GET ?path=/folder

• Get the listing/contents for the specified path
• Example: http://api.com:3000/filemanager/folder?path=/folder

POST path=/folder/file.ext&name=newfoldername

• Create a new folder at the provided path
• Example: http://api.com:3000/filemanager/folder?path=/&name=newFolderName

Reponses

Responses will be formatted in the following format.

{
    data: [],
    errors: []
}

The errors array should only exist when errors exist, making error checking as easy as if(obj.errors). Data should come back as an array of item objects whether it's 1 or a million objects. The item format looks like this

{
	"path":"/invoiceLayoutJSON.txt",
        "dir": "/",
	"directPath":"/static/invoiceLayoutJSON.txt",
        "preview": "/item/preview?path=/invoiceLayoutJSON.txt",
	"filename":"invoiceLayoutJSON.txt",
	"fileType":"txt",
	"isDirectory":false,
	"properties":{
		"dateCreated":"2016-08-15T16:18:28.890Z",
		"dateModified":"2016-08-15T16:18:28.891Z",
		"height":0,
                "width":0,
                "size":1963
		},
	"title":"invoiceLayoutJSON.txt",
	"key":"/invoiceLayoutJSON.txt"
}

The keys are as follows:

path: The path to the file. Should match what was passed in the request.

dir: The directory of the file.

directPath: The path the file can be directly accessed at.  For the nodejs api, this will still be an endpoint, for other api's on local servers, it may be a direct link to the file.

preview: A link to retrieve a thumbnail of an image or small portion of a text file.  Not currently implemented.

filename: The name of the file, i.e., the last part of the path.

fileType: The file extension, "dir" if a directory, or "txt" if missing/unknown.

isDirectory: true or false.

properties: A nested JSON object containing specific properties of the file.

	dateCreated: The file's creation date, if available.
	dateModified: The file's modification date, if available.
	height: If an image, the height in pixels.
	width: If an image, the width in pixels.
	size: The file size in bytes.

title: What will show up in the filetree.

key: A unique key for the filetree, currently using the full path of the file or directory.

The returned object should always be the acted upon item, or the items being retrieved. In other words, the array of objects for a folder listing, or the renamed object for a rename, and the new object after a move, or the deleted item for a delete.

Errors

An example error document should look like this

{
  "errors": [
    {
      "title": "Path not provided",
      "code": 404,
      "detail": "You must provide a path parameter, IE ?path=/folder/file.ext",
      "status": "error",
      "source": "parsePath"
    }
  ]
}