Difference between revisions of "Sugar Network/API"
Line 99: | Line 99: | ||
Some of resources have Wiki pages associated. The following actions can be used to manage these Wiki pages. | Some of resources have Wiki pages associated. The following actions can be used to manage these Wiki pages. | ||
− | GET /<RESOURCE>/<GUID>/wikitext | + | GET /<RESOURCE>/<GUID>/'''wikitext''' |
Get the Wiki sources. | Get the Wiki sources. | ||
Line 106: | Line 106: | ||
: Wiki sources with text/plain MIME type. | : Wiki sources with text/plain MIME type. | ||
− | GET /<RESOURCE>/<GUID>/rendered_wikitext | + | GET /<RESOURCE>/<GUID>/'''rendered_wikitext''' |
Get the Wiki rendered to HTML. | Get the Wiki rendered to HTML. | ||
Line 113: | Line 113: | ||
: Rendered Wiki with text/html MIME type. | : Rendered Wiki with text/html MIME type. | ||
− | PUT /<RESOURCE>/<GUID>/wikitext | + | PUT /<RESOURCE>/<GUID>/'''wikitext''' |
Put new content for Wiki page. Only object creator can use it. | Put new content for Wiki page. Only object creator can use it. |
Revision as of 12:38, 19 December 2011
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.
Common properties
All resources have the following properties:
ctime
, int
the UNIX seconds in UTC timezone of the time when object was created; optional, will be set on a server side otherwise;mtime
, int
the UNIX seconds in UTC timezone of the time when object was modified; optional, will be set on a server side otherwise;creator
, guid, read
the player who created the object.
Resources that can be voted (everything except player, report, comment and event), have these additional properties:
respect
, guid, read, create
what player needs to be respected on getting vote to this object, if empty, the associated project itself will be voted.
And calculated ones:
reputation
, int, read
current object's reputation;vote
, bool, read, write
did url requester voted for the current object or not.
Common actions
Actions might be restricted for particular resource, see the corresponding section for detailed information.
POST /<RESOURCE>
Create new RESOURCE object.
Sends:
- Resource properties.
Receives:
guid
, str
globally unique identifier that specifies created object;
PUT /<RESOURCE>/<GUID>
Modify the specified RESOURCE object. By default, might be called only by RESOURCE creator.
Sends:
- Keys that need to be modified.
DELETE /<RESOURCE>/<GUID>
Delete the specified RESOURCE object. The real destroying won't happen, the object will be hidden. The garbage collection of hidden objects will be processed by Network administrators. By default, might be called only by RESOURCE creator.
GET /<RESOURCE>?[query=<>][&offset=<>][&limit=<>][&properties=<PROP>[,..]][&order_by=[+|-]<PROP>[,..]]
Find RESOURCE objects.
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 RESOURCE properties to return; by default, return all properties;order_by
, str
coma separated list of RESOURCE properties to sort the resulting list; if an property starts with the-
, the order is descending, otherwise it is ascending;
Sends:
- A dictionary with RESOURCE's properties to restrict the resulting list.
Receives:
- An array of dictionaries with RESOURCE properties, dictionaries contain at least
guid
property.
- An array of dictionaries with RESOURCE properties, dictionaries contain at least
GET /<RESOURCE>/<GUID>[?properties=<PROP>[,..]]
Return RESOURCE properties the of particular object.
Where:
properties
, str
coma separated list of RESOURCE properties to return; by default, return all properties.
Receives:
- A dictionary with RESOURCE properties that contains at least
guid
property.
- A dictionary with RESOURCE properties that contains at least
Wiki actions
Some of resources have Wiki pages associated. The following actions can be used to manage these Wiki pages.
GET /<RESOURCE>/<GUID>/wikitext
Get the Wiki sources.
Receives:
- Wiki sources with text/plain MIME type.
GET /<RESOURCE>/<GUID>/rendered_wikitext
Get the Wiki rendered to HTML.
Receives:
- Rendered Wiki with text/html MIME type.
PUT /<RESOURCE>/<GUID>/wikitext
Put new content for Wiki page. Only object creator can use it.
Sends:
- Wiki sources with text/plain MIME type.
Events:
type: update
Common events
All events have the following common properties:
type
, str
the type of event;timestamp
, int
the UNIX seconds in UTC timezone of the time when event was created;resource
, str
the name of affected resource;object
, guid
the GUID of affected resource object;creator
the GUID of a player the event was created on behalf of.
Different types of events might add new options.
There are the following common event types:
- The particular resource was created:
type: create
- The particular resource properties were modified:
type: update
- The particular resource was deleted (hidden):
type: delete
Resources
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.
Sends:
- A dictionary with event properties.
Events:
- Direct event to the player:
type: message
.
project
Properties:
title
, str, read, write only for the team members
one line title;
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 creation, the creator will be the only team member;
- update and delete actions are allowed only for team members;
- Wiki related actions to manage object description.
POST /project/<GUID/add_member?member=<PLAYER>
Make a PLAYER the team member. Only team members can call this action.
Events:
type: add_member
;memeber: GUID
.
POST /project/GUID/remove_member?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.
Events:
type: remove_member
;memeber: GUID
.
question
Properties:
title
, str, read, write only for creator
one line title;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.
Actions:
- Wiki related actions to manage object description.
idea
Properties:
title
, str, read, write only for creator
one line title;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.
Actions:
- Wiki related actions to manage object description.
problem
Properties:
title
, str, read, write only for creator
one line title;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.
Actions:
- Wiki related actions to manage object description.
solution
The solution for question/idea/problem objects.
Properties:
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.
Actions:
- Wiki related actions to manage object description.
wiki
Properties:
title
, str, read, write only for creator
one line title;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;
Actions:
- Wiki related actions to manage Wiki page.
gallery
Properties:
title
, str, read, write only for creator
one line title;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;
Actions:
- Wiki related actions to manage object description.
GET /gallery/<GUID>/exhibit
Get the attached object.
Receives:
- Attached object content with application/octet-stream MIME type.
PUT /<RESOURCE>/<GUID>/exhibit
Put new attached object. Only object creator can use it.
Sends:
- Attached object content with application/octet-stream MIME type.
Events:
type: update
objective
Properties:
title
, str, read, write only for the team members
one line title;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;
Actions:
- Wiki related actions to manage object description.
release
comment
event
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.