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 operates with resources that are collections of objects. All objects are identified by global unique identifiers, GUIDs. Resources might support common actions. While processing requests, server might generate events. There are common events that all resources might generate.

The API is RESTful and being served via HTTP(S) using JSON notation. The common RESTful request url format is:

http[s]://<SERVER>/<RESOURCE>[/<GUID|ACTION>[/<ACTION>]]?<AUTH-TOKEN>=<>[&<ARG>=<>]..]

When:

• RESOURCE value is one of existing resources;
• GUID, the RESOURCE's particular object;
• ACTION and a set of ARGs depend on particular RESOURCE.

Besides, particular request can send and receive data in JSON notation. If request processing was failed, the reply is a JSON directory that contains error key with error message.

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 off-line schools.

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.

Objects

Common actions

Actions might be restricted for particular object, see the corresponding section for detailed information.

POST /<OBJECT>

Create new OBJECT item.

Inputs:

• ctime, int
  the UNIX seconds in UTC timezone of the time when item was created; optional, will be set on a server side otherwise;
• mtime, int
  the UNIX seconds in UTC timezone of the time when item was modified; optional, will be set on a server side otherwise;

Returns:

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

PUT /<OBJECT>/<GUID>

Modify the specified OBJECT item.

Inputs:

Keys that need to be modified.

DELETE /<OBJECT>/<GUID>

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

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

Find OBJECT 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 /<OBJECT>/<GUID>[?properties=<PROP>[,..]]

Return OBJECT 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.

player

Properties:

• nickname, str, read
  set by Sugar Shell;
• color, str, read
  colors pair in format #RRGGBB,#RRGGBB, set by Sugar Shell.

Calculated properties:

• reputation, int, read
  current player's reputation based on:
  • direct votes from other players,
  • votes given to objects where the player is a creator;
• vote, bool, read, write
  did url requester voted for the current object or not;

Actions:

• player cannot be created or destroyed;
• player can be updated only by a user who is associated with it.

POST /player/<GUID>/send

Send private message to the player.

Inputs:

A dictionary with event properties.

Event types:

• message, direct event to the player.

project

Properties:

• title, str, read, write only for the team members
  one line title;
• description, str, read, write only for the team members
  multi lined description;
• creator, guid, read
  the player who created the object;
• type, str, read, write only for the team members
  the project type:
  • general,
  • activity,
  • wiki,
  • gallery;
• zoom, str, read, write only for the team members
  Network Zoom level that project belongs:
  • worldwide,
  • neighbourhood,
  • private.

Calculated properties:

• reputation, int, read
  current project's reputation based on:
  • direct votes from other players,
  • votes given to related objects if theirs respect property is empty;
• vote, bool, read, write
  did url requester voted for the current object or not.

Many-to-many relations:

• team, relates to player.

Actions:

• right after create call, the creator player will be the only team member;
• update and destroy are allowed only for team members.

/project/add_member?guid=<PROJECT>&member=<PLAYER>

Make a PLAYER the team member. Only team members can call this action.

/project/remove_member?guid=<PROJECT>&member=<PLAYER>

Remove PLAYER from the to the team. Only team member can call this action if he is not the PLAYER and PLAYER is not the same as creator.

question

Properties:

• title, str, read, write only for creator
  one line title;
• description, str, read, write only for creator
  multi lined description;
• creator, guid, read
  the player who created the object;
• respect, guid, read, create
  what player needs to be respected on getting vote to this object, if empty, the project itself will be voted;
• solution, guid, read, write only by creator
  the solution which solves the object.

Calculated properties:

• reputation, int, read
  current object's reputation;
• vote, bool, read, write
  did url requester voted for the current object or not;
• implementation_status, str, read
  if question has an associated objective, this objective's status is a status of the question, otherwise the property is empty.

idea

Properties:

• title, str, read, write only for creator
  one line title;
• description, str, read, write only for creator
  multi lined description;
• creator, guid, read
  the player who created the object;
• respect, guid, read, create
  what player needs to be respected on getting vote to this object, if empty, the project itself will be voted.

Calculated properties:

• reputation, int, read
  current object's reputation;
• vote, bool, read, write
  did url requester voted for the current object or not;
• implementation_status, str, read
  if idea has an associated objective, this objective's status is a status of the idea, otherwise the property is empty.

problem

Properties:

• title, str, read, write only for creator
  one line title;
• description, str, read, write only for creator
  multi lined description;
• creator, guid, read
  the player who created the object;
• respect, guid, read, create
  what player needs to be respected on getting vote to this object, if empty, the project itself will be voted;
• solution, guid, read, write only by creator
  the solution which solves the object.

Calculated properties:

• reputation, int, read
  current object's reputation;
• vote, bool, read, write
  did url requester voted for the current object or not;
• implementation_status, str, read
  if problem has an associated objective, this objective's status is a status of the problem, otherwise the property is empty.

solution

The solution for question/idea/problem objects.

Properties:

• text, wikitext, read, write only for creator
  solution text;
• creator, guid, read
  the player who created the object;
• respect, guid, read, create
  what player needs to be respected on getting vote to this object, if empty, the project itself will be voted.

Calculated properties:

• reputation, int, read
  current object's reputation;
• vote, bool, read, write
  did url requester voted for the current object or not.

wiki

Properties:

• title, str, read, write only for creator
  one line title;
• description, str, read, write only for creator
  multi lined description;
• creator, guid, read
  the player who created the object;
• respect, guid, read, create
  what player needs to be respected on getting vote to this object, if empty, the project itself will be voted;
• reputation, int, read
  current object's reputation;
• vote, bool, read, write
  did url requester voted for the current object or not;

gallery

Properties:

• title, str, read, write only for creator
  one line title;
• description, str, read, write only for creator
  multi lined description;
• creator, guid, read
  the player who created the object;
• respect, guid, read, create
  what player needs to be respected on getting vote to this object, if empty, the project itself will be voted;
• reputation, int, read
  current object's reputation;
• vote, bool, read, write
  did url requester voted for the current object or not;

objective

Properties:

• title, str, read, write only for the team members
  one line title;
• description, str, read, write only for the team members
  multi lined description;
• creator, guid, read
  the player who created the object;
• respect, guid, read, create
  what player needs to be respected on getting vote to this object, if empty, the project itself will be voted;
• reputation, int, read
  current object's reputation;
• vote, bool, read, write
  did url requester voted for the current object or not;

Changelog

This section shows how API is evolving. The API state is being described by a version. The major number is being changed only if backwards compatibility was broken.

1.0

Not yet released API.