Data Storage Service Api (datastore)¶

new DataStore({service, domain, token})¶

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

Parameter

• service: The routing name of the DataStore 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 storage = new nive.DataStore({name:"mystorage"});
storage.getItem({key:'key1'})
   .done(function(data, message, jqXHR)   { console.log(data); } );

DataStore.getItem({key, owner})¶

DataStore.getItem({id})¶

Returns the stored item including value and timestamp for the key.

Parameter

• key: string. The items’ key.
• owner (optional): string. The items owner.
• id: number. The items’ unique id as alternativ to key/owner.

Returns

• key: string. The items key.
• value: text/number/json. The items value.
• timestamp: float. Utc time.
• id: number. Unique identifier of the item (only set if uniquemode is disabled).

Status codes

• 422 Empty or invalid key: Key parameter is invalid.
• 404 Not found: Item not found.

nive.DataStore({name:"mystorage"})
   .getItem({key: "key1"})
   .done(function (data, message, xhr) {
       // receive the result e.g.
       // {key: "key1", value: "value1", timestamp: 1234567.89, id: 1234567890}
       var value = data.value;
   });

GET http://mydomain.nive.io/mystorage/api/getItem?key=key1
=>
{"key": "key1", "value": "value1"}

DataStore.newItem({key, value, owner})¶

DataStore.newItem([items])¶

Creates a single item or a set of items as batch. Unlike DataStore.setItem() the function fails if one of the keys already exists. Use this function to make sure existing items will not be replaced accidentally.

Keys and values must match validation rules defined in the backend. Otherwise the function will throw and error.

Parameter

• key: string. The items key.
• value: string/number/json. The items value.
• owner (optional): string. The new items owner. By default the current user.
• items: list. A list of multiple key/value/owner items to create as batch. A maximum number of 20 items allowed.

Returns

• result: int. Number of items stored.
• success: list. List of [‘position’, ‘key’, ‘id’, ‘owner’, ‘timestamp’] infos referencing new items. ‘position’ is the transmitted items position in the batch.
• message (optional): string. Status message in case of a failure.
• invalid (optional): list. Additional infos pointing to the reason of the failure.

Status codes

• 401 Not allowed: Owner mismatch
• 413 Too many items: Limits exceeded.
• 422 Invalid data: Empty key, no value, invalid json or validation failure.

var newitems = [{key: "key1", value: "value1"}, {key: "key2", value: 1234}];

nive.DataStore({name:"mystorage"})
   .newItem({items: newitems})
   .done(function (data, message, xhr) {
       // success: items have been stored
       var number_stored = data.result;
   })
   .fail(function (jqXHR, message, error) {
       // error: something went wrong
       // handle message
   });

POST http://mydomain.nive.io/mystorage/api/newItem
    Content-Type: application/json
    Body: {"items": [{"key": "key1", "value": "value1"},
                     {"key": "key2", "value": 1234}]}
=>
{"result": 2}

DataStore.setItem({key, value, owner, id})¶

DataStore.setItem([items])¶

Store a set of items as batch. Creates or replaces items based on their keys. Use DataStore.newItem() instead if you want to make sure existing items will not be replaced.

Keys and values must match validation rules defined in the backend. Otherwise the function will throw and error.

Parameter

• key: string. The items key. Always required even if the items id is passed.
• value: string/number/json. The items value.
• owner (optional): string. The new items owner. By default the current user.
• id (optional): int. The items unique id.
• items: list. A list of multiple key/value/owner/id items to set as batch. A maximum number of 20 items allowed.

Returns

• result: int. Number of items stored.
• success: list. List of [‘position’, ‘key’, ‘id’, ‘owner’, ‘timestamp’] infos referencing new items. ‘position’ is the transmitted items position in the batch.
• message (optional): string. Status message in case of a failure.
• invalid (optional): list. Additional infos pointing to the reason of the failure.

Status codes

• 401 Not allowed: Owner mismatch
• 413 Too many items: Limits exceeded.
• 422 Invalid data: Empty key, no value, invalid json or validation failure.

var newItem = {key: 'key1', value: 'value1'};

nive.DataStore({name:"mystorage"})
   .setItem({items: newItem})
   .done(function (data, message, xhr) {
       // success: items have been stored
       var number_stored = data.result;
   })
  .fail(function (jqXHR, message, error) {
      // error: something went wrong
      // handle message
  });

// batch example
var newItems = [{key: 'key1', value: 'value1'}, {key: 'key2', value: 1234}];

nive.DataStore({name:"mystorage"})
   .setItem({items: newItems})
   .done(function (data, message, xhr) {
       // success: items have been stored
       var number_stored = data.result;
   })
   .fail(function (jqXHR, message, error) {
       // error: something went wrong
       // handle message
   });

POST http://mydomain.nive.io/mystorage/api/setItem
    Content-Type: application/json
    Body: {"key": "key1", "value": "value1"}
=>
{"result": 1}

DataStore.removeItem({key, owner})¶

DataStore.removeItem({id})¶

DataStore.removeItem([items])¶

Delete one or more items.

Request parameter

• key: string. The items key.
• owner (optional): string. The new items owner. By default the current user.
• id: int. The items unique id.
• items: list. A list of multiple key/owner/id items to remove as batch. A maximum number of 20 items allowed.

Returns

• result: int. Number of items removed
• success: list. List of [‘position’, ‘key’, ‘id’, ‘owner’] infos referencing deleted items. ‘position’ is the transmitted items position in the batch.
• message (optional): string. Status message in case of a failure.
• invalid (optional): list. Additional infos pointing to the reason of the failure.

Status codes

• 401 Not allowed: Owner mismatch
• 422 Invalid data: Empty key or validation failure

nive.DataStore({name:"mystorage"})
   .removeItem({key: "key1"})
   .done(function (data, message, xhr) {
       // success: item has been deleted if data.result is 1.
       number_deleted = data.result;
   });

POST http://mydomain.nive.io/mystorage/api/removeItem
    Content-Type: application/json
    Body: {"key": "key1"}
=>
{"result": 1}

DataStore.list({key, sort, order, size, start, owner})¶

Returns a list of batched items for a single or multiple keys.

Parameter

• key (optional): string/list. One or multiple keys.
• sort (optional): enum. Sort result either by ‘key’ (default), ‘timestamp’ or ‘value’.
• order (optional): enum. Order the result ascending ‘<’ or descending ‘>’.
• size (optional): int. Number of batched items. maximum is 100.
• start (optional): int. Start number of batched result sets.
• owner (optional): string. If ‘null’ limits result to items owned by current user. Use ‘sys:all’ as wildcard to matchh all owners. ‘sys:all’ does not affect security settings however.

Returns

• items: list. The list of matching items. Each returned item contains [‘key’, ‘value’, ‘timestamp’, ‘owner’, ‘id’]
• start: int. The start item number for a batched result set.
• size: int. The size of the current batch of items.
• message (optional): string. Status message in case of a failure.
• invalid (optional): list. Additional infos pointing to the reason of the failure.

Status codes

• 401 Not allowed: Owner mismatch
• 422 Invalid data: Empty key or validation failure

nive.DataStore({name: "mystorage"})
   .list({key: ["key1", "key2"], order: "<", start: 0, size: 20})
   .done(function (data, message, xhr) {
       // receive the result
       // e.g. {items: [{key: "key1", value: "value1"},...],
       //       start: 0, size: 20, total: 32}
       var value1 = result.items[0].value;
  });

GET http://mydomain.nive.io/mystorage/api/list?key=key1&start=0&size=20
=>
{"items": [{"key": "key1", "value": "value1"}, ...],
 "start": 0, "size": 20, "total": 32}

DataStore.keys({order, size, start, owner})¶

Returns a list of existing keys.

Parameter

• order (optional): enum. Order the result ascending ‘<’ or descending ‘>’.
• size (optional): int. Number of batched items. Maximum is 100.
• start (optional): int. Start number of batched result sets.
• owner (optional): string. If ‘null’ limits result to items owned by current user. Use ‘sys:all’ as wildcard to matchh all owners. ‘sys:all’ does not affect security settings however.

Returns

• keys: list. The list of matching keys.
• start: int. The start item number for a batched result set.
• size: int. The size of the current batch of items.
• message (optional): string. Status message in case of a failure.
• invalid (optional): list. Additional infos pointing to the reason of the failure

Status codes

• 401 Not allowed: Owner mismatch
• 422 Invalid data: Empty key or validation failure

nive.DataStore({name:"mystorage"})
   .keys({order: "<", start: 0, size: 20})
   .done(function (data, message, xhr) {
       // receive the result
       // e.g. {keys: ["key1", "key2"], start: 0, size: 20, total: 32}
       var key1 = result.keys[0];
   });

POST http://mydomain.nive.io/mystorage/api/keys
    Content-Type: application/json
    Body: {"start": 0, "size": 20}
=>
{"keys": ["key1", "key2"], "start": 0, "size": 20, "total": 32}

DataStore.allowed({permission})¶

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

Parameter

• permission (optional): list/string. One or multiple permissions.

Return values

• <permission name>:bool: Part of the result set. Permission name : true/false pair pointing out if the user has this particular permission.
• result: bool. The result is true if the user has all permissions.
• message: string. Status message returned by the server in case of failure.

Status codes

• 422 Invalid ‘permission’ parameter

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

// or

nive.DataStore({name: "mystorage"})
   .allowed({permission: ["list","keys"]})
   .done(function (data, message, xhr) {
       // data = {list:false, keys:true, result:false}
       if(data.keys)
           $('#message').text('You are allowed to query for keys.');
  });

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

DataStore.getPermissions()¶

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: string. Name of the permission.
• groups: list. List of assigned groups.

Status codes

• 422 Invalid or missing parameter

nive.DataStore({name: "mystorage"})
   .getPermissions()
   .done(function (data, message, xhr) {
       // data is a list of permission, group items
       // [
       //   {permission: "newItem", groups: ["sys:noone"]},
       //   {permission: "setItem", groups: ["sys:everyone"]},
       //   ...
       // ]
  });

POST http://mydomain.nive.io/mystorage/api/getPermissions
    Content-Type: application/json
    {}
=>
[
    {permission: "newItem", groups: ["sys:noone"]},
    {permission: "setItem", groups: ["sys:everyone"]},
    ...
]

DataStore.setPermissions({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"},
    ...
]

Actions

• ‘add’ will keep the current group(s) and add any missing.
• ‘replace’ overwrites assigned groups with the new ones.
• ‘revoke’ removes only the group(s) specified if assigned.

Parameter

for each permission

• permission: string. Name of permission to be updated.
• groups: list/string. Groups to be added, revoked or set depending on action.
• action: enum. ‘add’, ‘replace’, ‘revoke’. The action to execute.

Return values

• result: bool. Whether or not the function succeeded
• message: string. Status message returned by the server in case of failure.

Status codes

• 422 Invalid or missing parameter

var permissions = [
    {permission: "newItem", groups: ["sys:everyone"], action: "revoke"},
    {permission: "setItem", groups: ["sys:noone"], action: "replace"},
];
nive.DataStore({name: "mystorage"})
   .setPermissions(permissions)
   .done(function (data, message, xhr) {
       if(data.result)
           $('#message').text('Permissions have been updated.');
  });

POST http://mydomain.nive.io/mystorage/api/setPermissions
    Content-Type: application/json
    { permissions: [
        {permission: "newItem", groups: ["sys:everyone"], action: "revoke"},
        {permission: "setItem", groups: ["sys:noone"], action: "replace"},
    ]}
=>
{ result: true }

DataStore.getOwner({key})¶

DataStore.getOwner({id})¶

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

Parameter

• key: string/list. The items key or a list of keys.
• id: int/list. The items unique id or a list of ids.

Return values

• items: list. A list of items including {‘key’, ‘owner’, ‘id’}. ‘id’ is only set if uniquemode is disabled.
• message (optional): string. Status message in case of a failure.

Status codes

• 422 Invalid or missing parameter

nive.DataStore({name: "mystorage"})
   .getOwner({key: "key1"})
   .done(function (data, message, xhr) {
       var owner;
       if(data.items)
           owner = data.items[0].owner;
  });

POST http://mydomain.nive.io/mystorage/api/setPermissions
    Content-Type: application/json
    { key: "key1" }
=>
{ items: [{key: "key1", owner: "the-user", id: 1234567890}] }

DataStore.setOwner({newOwner, key, owner})¶

DataStore.setOwner({newOwner, id})¶

DataStore.setOwner({newOwner, [items]})¶

Change the owner of one or multiple items.

Parameter

• newOwner: string. The new owner.
• key: string. The items key.
• owner: string. The items current owner.
• id: int. The items unique id.
• items: list. A list of items specifying ‘key’, ‘owner’ or ‘id’.

Return values

• result: int. Number of items updated.
• success: list. List of [‘position’, ‘key’, ‘id’, ‘owner’, ‘timestamp’] infos referencing updated items. ‘position’ is the transmitted items position in the batch.
• message (optional): string. Status message in case of a failure.
• invalid (optional): list. Additional infos pointing to the reason of the failure.

Status codes

• 422 Invalid or missing parameter

nive.DataStore({name: "mystorage"})
   .setOwner({newOwner: "new-user", key: "key1"})
   .done(function (data, message, xhr) {
       // data.success contains infos about the updated item e.g.
       // [[0, "key1", 1234567890, "new-user", 1234567.89]
       if(data.result)
           $('#message').text('The owner has been updated.');
  });

POST http://mydomain.nive.io/mystorage/api/setOwner
    Content-Type: application/json
    { newOwner: "new-user", key: "key1" }
=>
{ result: 1, success: [[0, "key1", 1234567890, "new-user", 1234567.89]] }

DataStore.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.DataStore().ping()
   .done(function (data, message, xhr) {
       $('#message').text('Is alive!');
   });

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