Sugar Labs

Changes

Sugar Network/API (view source)

Revision as of 10:49, 19 December 2011

1,739 bytes added ,  10:49, 19 December 2011
→‎Objects
Line 27: Line 27:  
* The ''AUTH-TOKEN'' is the {{Code|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 ''AUTH-TOKEN'' is the {{Code|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 ==
   −
=== Common actions ===
+
Actions might be restricted for particular resource, see the corresponding section for detailed information.
   −
Actions might be restricted for particular object, see the corresponding section for detailed information.
+
POST /<RESOURCE>
   −
POST /<OBJECT>
+
Create new ''RESOURCE'' object.
   −
Create new ''OBJECT'' item.
+
Sends:
 +
:* {{Code|ctime}}, ''int''<br>the UNIX seconds in UTC timezone of the time when object was created; optional, will be set on a server side otherwise;
 +
:* {{Code|mtime}}, ''int''<br>the UNIX seconds in UTC timezone of the time when object was modified; optional, will be set on a server side otherwise;
   −
Inputs:
+
Receives:
−
:* {{Code|ctime}}, ''int''<br>the UNIX seconds in UTC timezone of the time when item was created; optional, will be set on a server side otherwise;
+
:* {{Code|guid}}, ''str''<br>globally unique identifier that specifies created object;
−
:* {{Code|mtime}}, ''int''<br>the UNIX seconds in UTC timezone of the time when item was modified; optional, will be set on a server side otherwise;
     −
Returns:
+
PUT /<RESOURCE>/<GUID>
−
:* {{Code|guid}}, ''str''<br>globally unique identifier that specifies created item;
     −
PUT /<OBJECT>/<GUID>
+
Modify the specified ''RESOURCE'' object. By default, might be called only by ''RESOURCE'' creator.
   −
Modify the specified ''OBJECT'' item.
+
Sends:
−
 
  −
Inputs:
   
: Keys that need to be modified.
 
: Keys that need to be modified.
   −
  DELETE /<OBJECT>/<GUID>
+
  DELETE /<RESOURCE>/<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.
+
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 /<OBJECT>?[query=<>][&offset=<>][&limit=<>][&properties=<PROP>[,..]][&order_by=<nowiki>[+|-]</nowiki><PROP>[,..]]
+
  GET /<RESOURCE>?[query=<>][&offset=<>][&limit=<>][&properties=<PROP>[,..]][&order_by=<nowiki>[+|-]</nowiki><PROP>[,..]]
   −
Find ''OBJECT'' items.
+
Find ''RESOURCE'' objects.
    
Where:
 
Where:
Line 63: Line 61:  
:* {{Code|offset}}, ''int''<br>start index to return entries from;
 
:* {{Code|offset}}, ''int''<br>start index to return entries from;
 
:* {{Code|limit}}, ''int''<br>do not return more then specified value;
 
:* {{Code|limit}}, ''int''<br>do not return more then specified value;
−
:* {{Code|properties}}, ''str''<br>coma separated list of ''OBJECT'' properties to return; by default, return all properties;
+
:* {{Code|properties}}, ''str''<br>coma separated list of ''RESOURCE'' properties to return; by default, return all properties;
−
:* {{Code|order_by}}, ''str''<br>coma separated list of ''OBJECT'' properties to sort the resulting list; if an property starts with the {{Code|-}}, the order is descending, otherwise it is ascending;
+
:* {{Code|order_by}}, ''str''<br>coma separated list of ''RESOURCE'' properties to sort the resulting list; if an property starts with the {{Code|-}}, the order is descending, otherwise it is ascending;
   −
Inputs:
+
Sends:
−
:* A dictionary with ''OBJECT'''s properties to restrict the resulting list.
+
:* A dictionary with ''RESOURCE'''s properties to restrict the resulting list.
   −
Returns:
+
Receives:
−
:* An array of dictionaries with ''OBJECT'' properties, dictionaries contain at least {{Code|guid}} property.
+
:* An array of dictionaries with ''RESOURCE'' properties, dictionaries contain at least {{Code|guid}} property.
   −
  GET /<OBJECT>/<GUID>[?properties=<PROP>[,..]]
+
  GET /<RESOURCE>/<GUID>[?properties=<PROP>[,..]]
   −
Return ''OBJECT'' properties the of particular item.
+
Return ''RESOURCE'' properties the of particular object.
    
Where:
 
Where:
−
:* {{Code|properties}}, ''str''<br>coma separated list of ''OBJECT'' properties to return; by default, return all properties.
+
:* {{Code|properties}}, ''str''<br>coma separated list of ''RESOURCE'' properties to return; by default, return all properties.
 +
 
 +
Receives:
 +
:* A dictionary with ''RESOURCE'' properties that contains at least {{Code|guid}} property.
 +
 
 +
=== 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.
   −
Returns:
+
PUT /<RESOURCE>/<GUID>/wikitext
−
:* A dictionary with ''OBJECT'' properties that contains at least {{Code|guid}} property.
+
 
 +
Put new content for Wiki page. Only object creator can use it.
 +
 
 +
Sends:
 +
: Wiki sources with text/plain MIME type.
 +
 
 +
Events:
 +
: {{Code|type: update}}
 +
 
 +
== Common events ==
 +
 
 +
All events have the following common properties:
 +
 
 +
* {{Code|type}}, ''str''<br>the type of event;
 +
* {{Code|timestamp}}, ''int''<br>the UNIX seconds in UTC timezone of the time when event was created;
 +
* {{Code|resource}}, ''str''<br>the name of affected resource;
 +
* {{Code|guid}}, ''guid''<br>the GUID of affected resource object;
 +
* {{Code|creator}}<br>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:
 +
:* {{Code|type: create}}
 +
 
 +
: The particular resource properties were modified:
 +
:* {{Code|type: update}}
 +
 
 +
: The particular resource was deleted (hidden):
 +
:* {{Code|type: delete}}
 +
 
 +
== Resources ==
    
=== player ===
 
=== player ===
Line 103: Line 154:  
Send private message to the ''player''.
 
Send private message to the ''player''.
   −
Inputs:
+
Sends:
 
: A dictionary with [[#event|event]] properties.
 
: A dictionary with [[#event|event]] properties.
   −
Event types:
+
Events:
−
:* {{Code|message}}, direct event to the ''player''.
+
: Direct event to the ''player'':
 +
:* {{Code|type: message}}.
    
=== project ===
 
=== project ===
Line 113: Line 165:  
Properties:
 
Properties:
 
:* {{Code|title}}, ''str'', ''read'', ''write'' only for the team members<br>one line title;
 
:* {{Code|title}}, ''str'', ''read'', ''write'' only for the team members<br>one line title;
−
:* {{Code|description}}, ''str'', ''read'', ''write'' only for the team members<br>multi lined description;
+
description;
 
:* {{Code|creator}}, ''guid'', ''read''<br>the ''player'' who created the object;
 
:* {{Code|creator}}, ''guid'', ''read''<br>the ''player'' who created the object;
 
:* {{Code|type}}, ''str'', ''read'', ''write'' only for the team members<br>the project type:
 
:* {{Code|type}}, ''str'', ''read'', ''write'' only for the team members<br>the project type:
Line 136: Line 188:  
Actions:
 
Actions:
   −
* right after '''create''' call, the creator ''player'' will be the only ''team'' member;
+
* right after creation, the creator will be the only ''team'' member;
−
* '''update''' and '''destroy''' are allowed only for ''team'' members.
+
* update and delete actions are allowed only for ''team'' members;
 +
* [[#Wiki_actions|Wiki related actions]] to manage object description.
   −
  /project/'''add_member'''?guid=<PROJECT>&member=<PLAYER>
+
  POST /project/<GUID/'''add_member'''?member=<PLAYER>
    
Make a ''PLAYER'' the ''team'' member. Only ''team'' members can call this action.
 
Make a ''PLAYER'' the ''team'' member. Only ''team'' members can call this action.
   −
  /project/'''remove_member'''?guid=<PROJECT>&member=<PLAYER>
+
Events:
 +
:* {{Code|type: add_member}};
 +
:* {{Code|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''.
 
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:
 +
:* {{Code|type: remove_member}};
 +
:* {{Code|memeber: GUID}}.
    
=== question ===
 
=== question ===
Line 151: Line 212:  
Properties:
 
Properties:
 
:* {{Code|title}}, ''str'', ''read'', ''write'' only for creator<br>one line title;
 
:* {{Code|title}}, ''str'', ''read'', ''write'' only for creator<br>one line title;
−
:* {{Code|description}}, ''str'', ''read'', ''write'' only for creator<br>multi lined description;
   
:* {{Code|creator}}, ''guid'', ''read''<br>the ''player'' who created the object;
 
:* {{Code|creator}}, ''guid'', ''read''<br>the ''player'' who created the object;
 
:* {{Code|respect}}, ''guid'', ''read'', ''create''<br>what ''player'' needs to be respected on getting vote to this object, if empty, the ''project'' itself will be voted;
 
:* {{Code|respect}}, ''guid'', ''read'', ''create''<br>what ''player'' needs to be respected on getting vote to this object, if empty, the ''project'' itself will be voted;
Line 160: Line 220:  
:* {{Code|vote}}, ''bool'', ''read'', ''write''<br>did url requester voted for the current object or not;
 
:* {{Code|vote}}, ''bool'', ''read'', ''write''<br>did url requester voted for the current object or not;
 
:* {{Code|implementation_status}}, ''str'', ''read''<br>if ''question'' has an associated ''objective'', this ''objective'''s status is a status of the ''question'', otherwise the property is empty.
 
:* {{Code|implementation_status}}, ''str'', ''read''<br>if ''question'' has an associated ''objective'', this ''objective'''s status is a status of the ''question'', otherwise the property is empty.
 +
 +
Actions:
 +
* [[#Wiki_actions|Wiki related actions]] to manage object description.
    
=== idea ===
 
=== idea ===
Line 165: Line 228:  
Properties:
 
Properties:
 
:* {{Code|title}}, ''str'', ''read'', ''write'' only for creator<br>one line title;
 
:* {{Code|title}}, ''str'', ''read'', ''write'' only for creator<br>one line title;
−
:* {{Code|description}}, ''str'', ''read'', ''write'' only for creator<br>multi lined description;
   
:* {{Code|creator}}, ''guid'', ''read''<br>the ''player'' who created the object;
 
:* {{Code|creator}}, ''guid'', ''read''<br>the ''player'' who created the object;
 
:* {{Code|respect}}, ''guid'', ''read'', ''create''<br>what ''player'' needs to be respected on getting vote to this object, if empty, the ''project'' itself will be voted.
 
:* {{Code|respect}}, ''guid'', ''read'', ''create''<br>what ''player'' needs to be respected on getting vote to this object, if empty, the ''project'' itself will be voted.
Line 173: Line 235:  
:* {{Code|vote}}, ''bool'', ''read'', ''write''<br>did url requester voted for the current object or not;
 
:* {{Code|vote}}, ''bool'', ''read'', ''write''<br>did url requester voted for the current object or not;
 
:* {{Code|implementation_status}}, ''str'', ''read''<br>if ''idea'' has an associated ''objective'', this ''objective'''s status is a status of the ''idea'', otherwise the property is empty.
 
:* {{Code|implementation_status}}, ''str'', ''read''<br>if ''idea'' has an associated ''objective'', this ''objective'''s status is a status of the ''idea'', otherwise the property is empty.
 +
 +
Actions:
 +
* [[#Wiki_actions|Wiki related actions]] to manage object description.
    
=== problem ===
 
=== problem ===
Line 178: Line 243:  
Properties:
 
Properties:
 
:* {{Code|title}}, ''str'', ''read'', ''write'' only for creator<br>one line title;
 
:* {{Code|title}}, ''str'', ''read'', ''write'' only for creator<br>one line title;
−
:* {{Code|description}}, ''str'', ''read'', ''write'' only for creator<br>multi lined description;
   
:* {{Code|creator}}, ''guid'', ''read''<br>the ''player'' who created the object;
 
:* {{Code|creator}}, ''guid'', ''read''<br>the ''player'' who created the object;
 
:* {{Code|respect}}, ''guid'', ''read'', ''create''<br>what ''player'' needs to be respected on getting vote to this object, if empty, the ''project'' itself will be voted;
 
:* {{Code|respect}}, ''guid'', ''read'', ''create''<br>what ''player'' needs to be respected on getting vote to this object, if empty, the ''project'' itself will be voted;
Line 187: Line 251:  
:* {{Code|vote}}, ''bool'', ''read'', ''write''<br>did url requester voted for the current object or not;
 
:* {{Code|vote}}, ''bool'', ''read'', ''write''<br>did url requester voted for the current object or not;
 
:* {{Code|implementation_status}}, ''str'', ''read''<br>if ''problem'' has an associated ''objective'', this ''objective'''s status is a status of the ''problem'', otherwise the property is empty.
 
:* {{Code|implementation_status}}, ''str'', ''read''<br>if ''problem'' has an associated ''objective'', this ''objective'''s status is a status of the ''problem'', otherwise the property is empty.
 +
 +
Actions:
 +
* [[#Wiki_actions|Wiki related actions]] to manage object description.
    
=== solution ===
 
=== solution ===
Line 193: Line 260:     
Properties:
 
Properties:
−
:* {{Code|text}}, ''wikitext'', ''read'', ''write'' only for creator<br>solution text;
   
:* {{Code|creator}}, ''guid'', ''read''<br>the ''player'' who created the object;
 
:* {{Code|creator}}, ''guid'', ''read''<br>the ''player'' who created the object;
 
:* {{Code|respect}}, ''guid'', ''read'', ''create''<br>what ''player'' needs to be respected on getting vote to this object, if empty, the ''project'' itself will be voted.
 
:* {{Code|respect}}, ''guid'', ''read'', ''create''<br>what ''player'' needs to be respected on getting vote to this object, if empty, the ''project'' itself will be voted.
Line 200: Line 266:  
:* {{Code|reputation}}, ''int'', ''read''<br>current object's reputation;
 
:* {{Code|reputation}}, ''int'', ''read''<br>current object's reputation;
 
:* {{Code|vote}}, ''bool'', ''read'', ''write''<br>did url requester voted for the current object or not.
 
:* {{Code|vote}}, ''bool'', ''read'', ''write''<br>did url requester voted for the current object or not.
 +
 +
Actions:
 +
* [[#Wiki_actions|Wiki related actions]] to manage object description.
    
=== wiki ===
 
=== wiki ===
Line 205: Line 274:  
Properties:
 
Properties:
 
:* {{Code|title}}, ''str'', ''read'', ''write'' only for creator<br>one line title;
 
:* {{Code|title}}, ''str'', ''read'', ''write'' only for creator<br>one line title;
−
:* {{Code|description}}, ''str'', ''read'', ''write'' only for creator<br>multi lined description;
   
:* {{Code|creator}}, ''guid'', ''read''<br>the ''player'' who created the object;
 
:* {{Code|creator}}, ''guid'', ''read''<br>the ''player'' who created the object;
 
:* {{Code|respect}}, ''guid'', ''read'', ''create''<br>what ''player'' needs to be respected on getting vote to this object, if empty, the ''project'' itself will be voted;
 
:* {{Code|respect}}, ''guid'', ''read'', ''create''<br>what ''player'' needs to be respected on getting vote to this object, if empty, the ''project'' itself will be voted;
 
:* {{Code|reputation}}, ''int'', ''read''<br>current object's reputation;
 
:* {{Code|reputation}}, ''int'', ''read''<br>current object's reputation;
 
:* {{Code|vote}}, ''bool'', ''read'', ''write''<br>did url requester voted for the current object or not;
 
:* {{Code|vote}}, ''bool'', ''read'', ''write''<br>did url requester voted for the current object or not;
 +
 +
Actions:
 +
* [[#Wiki_actions|Wiki related actions]] to manage Wiki page.
    
=== gallery ===
 
=== gallery ===
Line 215: Line 286:  
Properties:
 
Properties:
 
:* {{Code|title}}, ''str'', ''read'', ''write'' only for creator<br>one line title;
 
:* {{Code|title}}, ''str'', ''read'', ''write'' only for creator<br>one line title;
−
:* {{Code|description}}, ''str'', ''read'', ''write'' only for creator<br>multi lined description;
   
:* {{Code|creator}}, ''guid'', ''read''<br>the ''player'' who created the object;
 
:* {{Code|creator}}, ''guid'', ''read''<br>the ''player'' who created the object;
 
:* {{Code|respect}}, ''guid'', ''read'', ''create''<br>what ''player'' needs to be respected on getting vote to this object, if empty, the ''project'' itself will be voted;
 
:* {{Code|respect}}, ''guid'', ''read'', ''create''<br>what ''player'' needs to be respected on getting vote to this object, if empty, the ''project'' itself will be voted;
 
:* {{Code|reputation}}, ''int'', ''read''<br>current object's reputation;
 
:* {{Code|reputation}}, ''int'', ''read''<br>current object's reputation;
 
:* {{Code|vote}}, ''bool'', ''read'', ''write''<br>did url requester voted for the current object or not;
 
:* {{Code|vote}}, ''bool'', ''read'', ''write''<br>did url requester voted for the current object or not;
 +
 +
Actions:
 +
* [[#Wiki_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:
 +
: {{Code|type: update}}
    
=== objective ===
 
=== objective ===
Line 225: Line 315:  
Properties:
 
Properties:
 
:* {{Code|title}}, ''str'', ''read'', ''write'' only for the team members<br>one line title;
 
:* {{Code|title}}, ''str'', ''read'', ''write'' only for the team members<br>one line title;
−
:* {{Code|description}}, ''str'', ''read'', ''write'' only for the team members<br>multi lined description;
   
:* {{Code|creator}}, ''guid'', ''read''<br>the ''player'' who created the object;
 
:* {{Code|creator}}, ''guid'', ''read''<br>the ''player'' who created the object;
 
:* {{Code|respect}}, ''guid'', ''read'', ''create''<br>what ''player'' needs to be respected on getting vote to this object, if empty, the ''project'' itself will be voted;
 
:* {{Code|respect}}, ''guid'', ''read'', ''create''<br>what ''player'' needs to be respected on getting vote to this object, if empty, the ''project'' itself will be voted;
 
:* {{Code|reputation}}, ''int'', ''read''<br>current object's reputation;
 
:* {{Code|reputation}}, ''int'', ''read''<br>current object's reputation;
 
:* {{Code|vote}}, ''bool'', ''read'', ''write''<br>did url requester voted for the current object or not;
 
:* {{Code|vote}}, ''bool'', ''read'', ''write''<br>did url requester voted for the current object or not;
 +
 +
Actions:
 +
* [[#Wiki_actions|Wiki related actions]] to manage object description.
    
=== release ===
 
=== release ===
Line 236: Line 328:     
=== event ===
 
=== event ===
−
      
== Many-to-many relations ==
 
== Many-to-many relations ==
Retrieved from "https://wiki.sugarlabs.org/go/Special:MobileDiff/73415"