Sugar Network/API

This page describes the APi that Sugar Network clients use to interact with Sugar Network server. See also technical introduction page.

Overview

The API is RESTful and being served via HTTP(S) using JSON notation.

The common RESTful url format is:

http[s]://<SERVER>/<OBJECT>/<ACTION>?<AUTH-TOKEN>=<VALUE>[&<ARG>=<VALUE>]..]

For the beginning, API is not secure for reasons:

• Implement initial version in short period of time;
• The only users, for the beginning, are teachers and students from one-teacher scholls.

In particular:

• API is being provided only via HTTP;
• The AUTH-TOKEN is the uid which is a hashed value from Sugar profile public SSH key (the same as JID value in Sugar Shell but without the domain part) that does not require any handshake procedures.

The OBJECT value is one of the following objects. When ACTION and a set of ARGs depend on OBJECT. Besides, particular ACTION can input and return data in JSON notation. If ACTION was failed, it returns the JSON directory that contains error key with error message.

Objects

The common COMMANDs are:

/create

Create new OBJECT item. Inputs:

• ctime int, the UNIX seconds time of entry creation; optional, will be set on a server side otherwise;
• mtime int, the UNIX seconds time of entry modification; optional, will be set on a server side otherwise;

Returns:

• guid str, globally unique identifier that specifies created item;

/update?guid=<>

Modify the specified item.

Inputs:

Keys that need to be modified.

/delete?guid=<>

Delete the specified item. The real destroying won't happen, the item will be hidden. The garbage collection of hidden items will be processed by Network administrators.

/find?[query=<>][&offset=<>][&limit=<>][&properties=<PROP>[,..]][&order_by=[+|-]<PROP>[,..]]

Find items. Where:

• query str, search request in Xapian notation;
• offset int, start index to return entries from;
• limit int, do not return more then specified value;
• properties str, coma separated list of OBJECT properties to return; by default, return all properties;
• order_by str, coma separated list of OBJECT properties to sort the resulting list; if an property starts with the -, the order is descending, otherwise it is ascending;

Inputs:

• A dictionary with OBJECT's properties to restrict the resulting list.

Returns:

• An array of dictionaries with OBJECT properties, dictionaries contain at least guid property.

/get?guid=<>[&properties=<PROP>[,..]]

Return properties the of particular item. Where:

• properties str, coma separated list of OBJECT properties to return; by default, return all properties.

Returns:

• A dictionary with OBJECT properties that contains at least guid property.