File Storage Service Api (filestore)¶

new FileStore({name, domain, token})¶

Service connector constructor. Takes all options to connect to the service.

Parameter

• service: The routing name of the FileStore service to connect.
• domain (optional): The subdomain name or fully qualified domain name. e.g ‘mydomain’ will be extended to ‘mydomain.nive.io’. The domain is only required for cross domain calls or in development mode.
• token (optional): The security token returned by User.token() to authenticate the user. Browser based applications can also call User.signin() to retrieve the token as cookie to be handled automatically by the browser.

See Endpoints for API calls for all supported options.

var app = new nive.FileStore({name:"myapp"});
app.list({path:"/"});

// or

nive.FileStore({name:'myapp'}).list({path:"/"});

FileStore.getItem({path})¶

Returns file or directory properties in json format.

Parameter

• path: the items path

Returns

• name (string): name of the file or directory
• type (string): ‘f’=file, ‘d’=directory
• mtime (datetime): modified time
• ctime (datetime): create time
• size (number): size in bytes (file only)
• mime (string): the associated mime-type (file only)
• header (string): custom file header (file only)
• cache (string): cache header setting

e.g.

{"name":"index.html", "type":"f",
 "size":2312, "mime":"text/html", "cache": "",
 "mtime":"2014/03/01 12:15:10", "ctime":"2014/03/01 11:15:10"}

Status codes

• 404 Not found: Item not found.

nive.FileStore({name:'myapp'}).getItem({path:'/index.html'})
  .done(function (data, message, xhr) {
    // receive the result as data
    details = data;
  });

Prefix the method with '@' to avoid overlapping directory or file names

GET http://mydomain.nive.io/myapp/index.html/@getItem
=>
{"name":"index.html", "type":"f", "size":2312, "mime":"text/html"}

FileStore.newItem({path, name, contents, type, mime, header, decode})¶

Create a new file or directory with the given path.

Parameter

• path: base path for the new item.
• name: the name of the new item. If empty and contents is a file the files’ name is used.
• contents (optional): file contents as string or file upload. Leave empty if new item is a directory.
• type (optional): either ‘file’ (f) or ‘directory’ (d)
• mime (optional): the files mimetype
• header (optional): custom header as json string
• decode (optional): if contents are base64 formatted set ‘decode=true’ to decode binary data.

Returns

• result: returns whether the new item has been created.
• message (optional): status message in case of a failure
• invalid (optional): list of additional infos pointing to the reason of the failure

Status codes

• 404 Not found: path does not exist
• 409 Item exists: A item with the given name already exists
• 413 Limits exceeded: Too many items or storage exceeded
• 422 Invalid parameter: contents or meta info not valid

----

----

FileStore.setItem({path, contents, mime, header, decode})¶

Update a file or directory with the given contents or meta information.

Parameter

• path: path of the item to be updated
• contents (optional): file contents as string or file upload. Leave empty if new item is a directory.
• mime (optional): the files mimetype
• header (optional): custom header as json string
• decode (optional): if contents are base64 formatted set ‘decode=true’ to decode binary data.

Returns

• result: returns whether the item has been updated.
• message (optional): status message in case of a failure
• invalid (optional): list of additional infos pointing to the reason of the failure

Status codes

• 404 Not found: path does not exist
• 413 Limits exceeded: Too many items or storage exceeded
• 422 Invalid parameter: contents or meta info not valid

----

----

FileStore.removeItem({path, recursive})¶

Delete a file or directory. If ‘path’ references a non empty directory ‘recursive’ must be set to true.

Parameter

• path: path of the item to be updated
• recursive (optional): ‘false’ by default. set to ‘true’ to delete a directory including subtree.

Returns

• result: number of items deleted
• message (optional): status message in case of a failure

Status codes

• 404 Not found: path does not exist
• 422 Invalid parameter: invalid path

----

----

FileStore.read({path})¶

Read the files contents.

Parameter

• path: path of the item to be updated

Returns

• <File data>

Status codes

• 404 Not found: path does not exist

----

----

FileStore.write({path, contents})¶

Update the files contents.

Parameter

• path: path of the item to be updated
• contents: file contents as string or file upload.

Returns

• result: returns whether the item has been updated
• message (optional): status message in case of a failure

Status codes

• 404 Not found: path does not exist
• 422 Invalid parameter: invalid contents

----

----

FileStore.move({path, newpath})¶

Move a file or folder to a new path.

Parameter

• path: path of the item to be moved
• newpath: new path of the item

Returns

• result: returns whether the item has been moved to the new path
• message (optional): status message in case of a failure

Status codes

• 404 Not found: path does not exist
• 413 Limits exceeded: Too many directory levels
• 422 Invalid parameter: invalid contents

----

----

FileStore.list({path, type, sort, order, size, start})¶

Returns a detailed list of contained files and directories.

Parameter

• path: path to the directory to list contents for
• type (optional): all (default), file (f), directory (d)
• sort (optional): sort by ‘name’, ‘size’, ‘type’, ‘mtime’, ‘ctime’
• order (optional): ‘<’,’>’. order the result list based on values ascending ‘<’ or descending ‘>’
• size (optional): batch size. default = 20
• start (optional): batch start number

Returns

• items: the list of matching items
• start: if batched the start number of the current batch
• size: batch size

Each item contains the following information:

• name (string): name of the file or folder
• type (string): f=file, d=directory
• size (number): size in bytes
• mime (string): the associated mime-type
• mtime (datetime): modified time in utc
• ctime (datetime): create time in utc

e.g. [{"name":"index.html", "type":"f", "size":2312, "mime":"text/html", "mtime":"2014/03/01 12:15:10"}]

nive.FileStore({name:'myapp'}).list({path:'/myfolder', type:'all'})
  .done(function (data, message, xhr) {
    // receive the result as data
    detailed_listing = data;
  });

Prefix the method with '@' to avoid overlapping directory or file names ::

GET http://mydomain.nive.io/myapp/myfolder/@list
=>
[
 {"name":"subfolder", "type":"d", "size":0, "mime":""},
 {"name":"index.html", "type":"f", "size":2312, "mime":"text/html"}
]

FileStore.allowed({path, permission})¶

Checks whether or not the current user has the given permission(s).

Parameter

• path: the items path
• permission (optional): one or multiple permissions

Return values

• result: true or false. The result is true if the user has all permissions.
• <permission name>: permission name pointing out if the user has this particular permission.
• invalid: (only set in case of failure) points to invalid parameters transfered
• message: (only set in case of failure) a status message returned by the server

Status codes

• 422 Invalid ‘permission’ parameter

nive.FileStore({name:'mystorage'}).allowed({permission:'list'})
  .done(function (data, message, xhr) {
    if(!data.result)
      $('#message').text('You are not allowed to list items.');
  });

POST http://mydomain.nive.io/mystorage/api/allowed
    Content-Type: application/json
    {"permission":"list"}
=>
{"result": false, "list": false}

FileStore.getPermissions({path})¶

Retrieve all permissions and assigned groups of this service. The result contains a list of permission and groups items.

[
    {permission: "newItem", groups: ["sys:noone"]},
    {permission: "setItem", groups: ["sys:everyone"]},
    ...
]

Return values

The function returns a permission:name, groups:list item for each permission. [{permission:name, groups:list}, ...]

• permission: the permissions name
• groups: a list of assigned groups

Status codes

• 422 Invalid or missing parameter

---

---

FileStore.setPermissions({path, permissions})¶

Update a single or multiple service permissions. Each permission to be updated must include the name, one or multiple groups and a action: ‘add’ (default), ‘replace’, ‘revoke’.

[
    {permission: "newItem", groups: ["sys:noone"], action: "replace"},
    {permission: "setItem", groups: ["sys:everyone"], action: "revoke"},
    ...
]

Parameter

• path: the items path
• permissions: a list of permissions to be updated

for each permission

• permission: permission name to be updated
• groups: groups to be added, revoked or set depending on action
• action: ‘add’, ‘replace’, ‘revoke’

Return values

• result: true or false whether or not the function succeeded
• message: (only set in case of failure) a status message returned by the server

Status codes

• 422 Invalid or missing parameter

---

---

FileStore.getOwner({path})¶

Retrieve the owner of a item referenced by key or id. This function returns a list of all matching items.

Parameter

• path: the items path

Return values

• items: a list of items including [‘path’, ‘owner’]
• message (optional): status message in case of a failure

Status codes

• 422 Invalid or missing parameter

---

---

FileStore.setOwner({path, owner})¶

Change the owner of the given item.

Parameter

• path: the items path
• owner: the items new owner

Return values

• result: whether or not the function succeeded

Status codes

• 422 Invalid or missing parameter

---

---

FileStore.ping({fake})¶

Simple test and health check function.

Parameter

• fake: fake http response status e.g. 422

Return values

• result: true if ‘fake’ is empty or 200 otherwise false

nive.FileStore().ping()
  .done(function (data, message, xhr) {
    $('#message').text('Seems alive!');
  });

GET http://mydomain.nive.io/mystorage/api/ping
    Content-Type: application/json
    {"active": true}
=>
{"result": 1}