Sugar Labs

Changes

Sugar Network/API (view source)

Revision as of 08:56, 27 September 2014

7,148 bytes added ,  08:56, 27 September 2014
→‎Base API
Line 1: Line 1: −
This page describes the APi that Sugar Network clients use to interact with Sugar Network server. See also [[Sugar_Network|technical introduction]] page.
+
This page describes the API that Sugar Network clients use to interact with a Sugar Network server. See also a guide to basic Sugar Network [[Sugar_Network/Concept|concepts]] and [[Platform_Team/Sugar_Network/Architecture|its twin page]] for a technical point of view. In addition, visit the [[Sugar_Network|introduction page]].
 +
 
 +
{{Note/warning|Note|Until announcing API freeze, this document describes the most recent development version of the API.<br>You can find its implementation on the [[#API servers|node-devel.sugarlabs.org]] server.}}
    
== Overview ==
 
== Overview ==
   −
The API operates with [[#Resources|resources]] that are collections of objects. All objects are identified by global unique identifiers, GUIDs. Resources might support [[#Common_actions|common actions]]. While processing requests, server might generate [[#events|events]]. There are [[#Common_events|common events]] that all resources might generate.
+
To better understand this API, see a technical explanation of its [[Platform_Team/Sugar_Network/Architecture#Conceptual_level|conceptual level]] and [[#Sugar_Network_resources|objects model]] in particular.
   −
The API is [[Wikipedia:Restful|RESTful]] and being served via HTTP(S) using [[Wikipedia:Json|JSON]] notation. The common RESTful request url format is:
+
The API operates with [[Sugar Network]] [[#Sugar_Network_resources|resources]], which are collections of objects. All objects are identified by globally unique identifiers, GUIDs, and available for operation via [[#Base_API|basic actions]]. The API is being provided from a [[#API_servers|node server]] or a [[#Client_API|client]]. While processing requests, API providers generate [[#Notifications|events]].
   −
  http[s]://<SERVER>/<RESOURCE>[/<GUID|ACTION>[/<ACTION>]]?<AUTH-TOKEN>=<>[&<ARG>=<>]..]
+
The API is [[Wikipedia:Restful|RESTful]], and is served via HTTP(S) using [[Wikipedia:Json|JSON]] notation. The common request url format is:
 +
 
 +
  http[s]://''SERVER''[/''RESOURCE''[/''GUID''[/''PROPERTY'']]][?[cmd=''COMMAND''][&''ARGUMENT''=''VALUE''..]]
    
When:
 
When:
   −
* ''RESOURCE'' value is one of [[#Resources|existing]] resources;
+
* {{Code|SERVER}}, [[#API_servers|particular]] Sugar Network API server;
−
* ''GUID'', the ''RESOURCE'''s particular object;
+
* {{Code|RESOURCE}}, name one of the [[#Sugar_Network_resources|existing]] resources;
−
* ''ACTION'' and a set of ''ARG''s depend on particular ''RESOURCE''.
+
* {{Code|GUID}}, the {{Code|RESOURCE}}'s particular object;
 +
* {{Code|PROPERTY}}, particular property of {{Code|GUID}} object;
 +
* {{Code|COMMAND}}, optional command name; combination of HTTP request method ({{Code|GET}}, {{Code|POST}}, {{Code|PUT}}, or, {{Code|DELETE}}) and [possibly empty] {{Code|COMMAND}} composes the requested [[#Actions|action]];
 +
* {{Code|ARGUMENT}}s and {{Code|VALUE}}s depend on the particular [[#Actions|action]].
 +
 
 +
In most cases, the server replies in JSON notation. If a request fails, the replied JSON object will contain a {{Code|request}} key, with the original request, and {{Code|error}} key, with an error message.
 +
 
 +
== API version ==
 +
 
 +
Sugar Network nodes might support multiple API versions at once but only one of them is default, i.e., the one which is in use if clients do not specify particular API version. To specify API versions in client request, setup the {{Code|X-API}} HTTP header with chosen version. If such header is omitted, default version will be used by the node;
 +
 
 +
Currently available API versions:
 +
 
 +
* ''0.1'' initial API implementation, should not be used;
 +
* ''0.2'' the most recent version, the rest of the document describes exactly this version.
 +
 
 +
== Nodes ==
 +
 
 +
These are standard Sugar Network API servers publicly available.
 +
 
 +
* [http://node-devel.sugarlabs.org/ node-devel.sugarlabs.org]<br>Development server which does not contain important data and is free for any experiments (administrative privileges for anonymous users); default API version is ''0.2'';
   −
Besides, particular request can send and receive data in [[Wikipedia:Json|JSON]] notation. If request processing was failed, the reply is a JSON directory that contains {{Code|error}} key with error message.
+
* [http://node-testing.sugarlabs.org/ node-testing.sugarlabs.org]<br>Recent stable release with regular data import from the production server; is still free for any experiments; default API version is ''0.1'';
   −
For the beginning, API is not secure for reasons:
+
* [http://node.sugarlabs.org/ node.sugarlabs.org]<br>Production server;
   −
* Implement initial version in short period of time;
+
* [http://localhost:5001/ localhost:5001]<br>default url to get access to [[#Client_API|local proxy]] provided from user side application; ; default API version is ''0.1''.
−
* The only users, for the beginning, are teachers and students from one-teacher off-line schools.
     −
In particular:
+
== Resources ==
   −
* API is being provided only via HTTP;
+
{{:Sugar_Network/Resources}}
−
* 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.
     −
=== Common properties ===
+
== Base API ==
   −
All resources have the following properties:
+
List of actions common of all API providers.
   −
* {{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;
+
<div id="POST"></div>
−
* {{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;
  −
* {{Code|creator}}, ''guid'', ''read''<br>the ''player'' who created the object.
     −
=== Common actions ===
+
'''POST''' /''RESOURCE''
   −
Actions might be restricted for particular resource, see the corresponding section for detailed information.
+
Create new resource object.
   −
POST /<RESOURCE>
+
JSON object keys to send:
 +
* {{Code|''RESOURCE}}'s properties.
   −
Create new ''RESOURCE'' object.
+
JSON object keys to receive:
 +
* {{Code|guid}}, with globally unique identifier that specifies the created object.
   −
Sends:
+
<div id="PUT"></div>
−
: Resource properties.
     −
Receives:
+
'''PUT''' /''RESOURCE''/''GUID''
−
:* {{Code|guid}}, ''str''<br>globally unique identifier that specifies created object;
     −
PUT /<RESOURCE>/<GUID>
+
Modify resource object. By default, might be called only by {{Code|GUID}} creator.
   −
Modify the specified ''RESOURCE'' object. By default, might be called only by ''RESOURCE'' creator.
+
JSON object keys to send:
 +
* {{Code|RESOURCE}}'s properties to modify.
   −
Sends:
+
<div id="DELETE"></div>
−
: Keys that need to be modified.
     −
  DELETE /<RESOURCE>/<GUID>
+
  '''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.
+
Delete resource object. Actual object destruction won't happen, the object will be hidden. Garbage collection of hidden objects will be processed by Network administrators. By default, this action may be called only by the {{Code|GUID}} creator.
   −
GET /<RESOURCE>?[query=<>][&offset=<>][&limit=<>][&properties=<PROP>[,..]][&order_by=<nowiki>[+|-]</nowiki><PROP>[,..]]
+
<div id="GET"></div>
   −
Find ''RESOURCE'' objects.
+
'''GET''' /''RESOURCE''[?offset=''INTEGER''][&limit=''INTEGER''][&query=''STRING''][&reply=''PROP''][&order_by=<nowiki>[+|-]</nowiki>''PROP''][&group_by=''PROP''][&''PROP''=''VALUE''][&''!PROP''=''VALUE'']
 +
 
 +
Find resource objects.
    
Where:
 
Where:
−
:* {{Code|query}}, ''str''<br>search request in [http://xapian.org/docs/queryparser.html Xapian] notation;
+
* {{Code|offset}}, ''int''<br>start index to return entries from, the default value is {{Code|0}};
−
:* {{Code|offset}}, ''int''<br>start index to return entries from;
+
* {{Code|limit}}, ''int''<br>do not return more then specified value, maximal and default values are being setup on server side;
−
:* {{Code|limit}}, ''int''<br>do not return more then specified value;
+
* {{Code|query}}, ''str''<br>search request in [http://xapian.org/docs/queryparser.html Xapian] notation; if property is boolean, integer or datetime, it supports searching by ranges, i.e., {{Code|''PROP'':[''START'']..[''END'']}};
−
:* {{Code|properties}}, ''str''<br>coma separated list of ''RESOURCE'' properties to return; by default, return all properties;
+
* {{Code|PROP}}, ''str''<br>supplements {{Code|query}} with filtering by exact value of the {{Code|PROP}} property; the resulting query string will be {{Code|''PROP''<nowiki>=</nowiki>''VALUE'' AND (''QUERY'')}}; argument is multiple;
−
:* {{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;
+
* {{Code|!PROP}}, ''str''<br>supplements {{Code|query}} by excluding exact value of the {{Code|PROP}} property; the resulting query string will be {{Code|NOT ''PROP''<nowiki>=</nowiki>''VALUE'' AND (''QUERY'')}}; argument is multiple;
 +
* {{Code|reply}}, ''str''<br>''RESOURCE'' properties to return; by default, return only {{Code|guid}} property; argument is multiple;
 +
* {{Code|order_by}}, ''str''<br>property to sort the resulting list by; if starts with the {{Code|-}}, the order is descending, otherwise it is ascending;
 +
* {{Code|group_by}}, ''str''<br>property name to group resulting list by.
 +
 
 +
JSON object keys to receive:
 +
* {{Code|total}}, total number in requested query (the reply might contain only the portion restricted by {{Code|limit}} request argument);
 +
* {{Code|result}}, an array of dictionaries with resource object properties, dictionaries contain at least {{Code|guid}} property.
 +
 
 +
<div id="GET-resource"></div>
 +
 
 +
'''GET''' /''RESOURCE''/''GUID''[?reply=''PROP'']
 +
 
 +
Where:
 +
* {{Code|reply}}, ''str''<br>''RESOURCE'' properties to return; by default, return only {{Code|guid}} property; argument is multiple;
 +
 
 +
Return properties for a particular resource object.
 +
 
 +
JSON object keys to receive:
 +
* properties that were specified in {{Code|reply}} argument(s), at least {{Code|guid}}.
 +
 
 +
<div id="PUT-property"></div>
 +
 
 +
'''PUT''' /''RESOURCE''/''GUID''/''PROP''
 +
 
 +
Modify particular resource property. By default, might be called only by {{Code|GUID}} creator.
 +
 
 +
<div id="GET-property"></div>
 +
 
 +
'''GET''' /''RESOURCE''/''GUID''/''PROP''
 +
 
 +
Return property value for particular resource object.
 +
 
 +
Data to receive:
 +
* property value in JSON notation for regular properties;
 +
* raw data or redirection for BLOB properties.
 +
 
 +
=== Aggregated properties ===
 +
 
 +
[[#resource-types|Aggregated]] properties have special API to treat their content.
 +
 
 +
<div id="POST-aggproperty"></div>
 +
 
 +
'''POST''' /''RESOURCE''/''GUID''/''PROP''
 +
 
 +
Submit new item. The command returns an id for newly created aggregated item. Depending on particular property, new items might be created not only by object's authors.
 +
 
 +
<div id="PUT-aggproperty"></div>
 +
 
 +
'''PUT''' /''RESOURCE''/''GUID''/''PROP''/''ID''
   −
Sends:
+
Update existing aggregated item. Depending on particular property, the command is allowed either to object's authors or to aggregated item submitter.
−
:* A dictionary with ''RESOURCE'''s properties to restrict the resulting list.
     −
Receives:
+
<div id="DELETE-aggproperty"></div>
−
:* An array of dictionaries with ''RESOURCE'' properties, dictionaries contain at least {{Code|guid}} property.
     −
  GET /<RESOURCE>/<GUID>[?properties=<PROP>[,..]]
+
  '''DELETE''' /''RESOURCE''/''GUID''/''PROP''/''ID''
   −
Return ''RESOURCE'' properties the of particular object.
+
Delete existing aggregated item. Depending on particular property, the command is allowed either to object's authors or to aggregated item submitter.
   −
Where:
+
=== Notifications ===
−
:* {{Code|properties}}, ''str''<br>coma separated list of ''RESOURCE'' properties to return; by default, return all properties.
+
 
 +
It is possible to subscribe to server events. Notification will happen using HTML5 [[wikipedia:Server-sent_events|Server-sent events]] (SSE).
 +
 
 +
To start subscription, send the following request:
 +
 
 +
'''GET''' /?cmd='''subscribe'''
 +
 
 +
Response will be served with ''text/event-stream'' MIME type for default SSE message type. SSE message will be a JSONified object with the following, at least, attributes:
 +
 
 +
* {{Code|event}}<br>event type.
 +
 
 +
== Node API ==
 +
 
 +
This is an API provided by Sugar Network nodes on top of [[#Base_API|base one]].
 +
 
 +
=== Authentication ===
 +
 
 +
Right now, the only way to be authenticated on a Sugar Network server is by running a [[Platform_Team/Sugar_Network/Implementation#sugar-network-client|local application]] on the client side and using the API it [[#Client_API|provides]].
 +
 
 +
''TODO''
   −
Receives:
+
=== Authorization ===
−
:* A dictionary with ''RESOURCE'' properties that contains at least {{Code|guid}} property.
     −
=== Wiki actions ===
+
Read-only access is available for anonymous requests, except special content like machine serial numbers. But to process any changes, clients need to be authenticated.
   −
Some of resources have Wiki pages associated. The following actions can be used to manage these Wiki pages.
+
Right after creating any Sugar Network object, its author becomes the only user who can process any object modifications afterwards. Authority information will be kept in the [[#Sugar_Network_resources|author]] property and can be modified using the following commands.
   −
  GET /<RESOURCE>/<GUID>/wikitext
+
  '''PUT''' /''RESOURCE''/''GUID''?cmd='''useradd'''&user=''USER''&role=''ROLE''
   −
Get the Wiki sources.
+
Add another user who can modify the corresponding object. ''USER'' argument should be either ''User'' guid (for authors registered in the Sugar Network), or, full author name.
   −
Receives:
+
'''PUT''' /''RESOURCE''/''GUID''?cmd='''userdel'''&user=''USER''
−
: Wiki sources with text/plain MIME type.
     −
GET /<RESOURCE>/<GUID>/rendered_wikitext
+
Remove user from the authority list. It is not possible to remove yourself. ''USER'' argument should be either ''User'' guid (for authors registered in the Sugar Network), or, full author name.
   −
Get the Wiki rendered to HTML.
+
''TODO''
   −
Receives:
+
=== Retrieving releases ===
−
: Rendered Wiki with text/html MIME type.
     −
PUT /<RESOURCE>/<GUID>/wikitext
+
To easy download Context [[#context-releases|releases]] and avoid reading raw ''Context.releases'' property, there are special high-level API commands.
   −
Put new content for Wiki page. Only object creator can use it.
+
<div id="GET-solve"></div>
   −
Sends:
+
'''GET''' /context/''GUID''?cmd='''solve'''[&lsb_id=''LSB_ID''][&lsb_release=''LSB_RELEASE''][&assume=''DEPENDENCY''-''VERSION'']
−
: Wiki sources with text/plain MIME type.
     −
Events:
+
The command returns information about what particular releases should be downloaded depending on provided requirements. This command might return not only one release, e.g., activities might have dependencies either system packages or another Sugar Network Contexts.
−
: {{Code|type: update}}
     −
=== Common events ===
+
Solving requirements might be:
   −
All events have the following common properties:
+
* {{Code|LSB_ID}}, if Context releases depend on system packages, specify the [[Wikipedia:Linux_Standard_Base|LSB]] distributor id to consider while choosing particular packages;
 +
* {{Code|LSB_RELEASE}}, if Context releases depend on system packages, specify the [[Wikipedia:Linux_Standard_Base|LSB]] release number of the distribution to consider while choosing particular packages;
 +
* {{Code|DEPENDENCY-VERSION}}, the {{Code|assume}} argument instructs server to assume that specified [[Sugar_Network/Recipe_Specification#Dependencies|dependency]] is already available on client side and should be taken into account while solving; this is especially important for package dependencies when server considers packages available only from official repositories but users might have more recent package versions installed in local system; e.g., the above example request will fail without {{Code|sugar-0.94}} because neither {{Code|lsb_id}} nor {{Code|lsb_release}} were specified (even if LSB information is passed, server might not have information about what package versions come from official repositories).
   −
* {{Code|type}}, ''str''<br>the type of event;
+
The resulting info is a JSON object with keys equal to Context guids and value objects for chosen release with the following keys:
−
* {{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|object}}, ''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.
+
* {{Code|blob}}, bundle [[#resource-types|digest]] to download;
 +
* {{Code|version}}, chosen version number;
 +
* {{Code|title}}, the ''Context.title'' value;
 +
* {{Code|command}}, a command to launch the bundle, only for Sugar activities.
   −
There are the following common event types:
+
For example, the {{Code|'''GET''' <nowiki>/context/org.laptop.TurtleArtActivity?cmd=solve&assume=sugar-0.94</nowiki>}} request returns:
   −
: The particular resource was created:
+
{
−
:* {{Code|type: create}}
+
  "org.laptop.TurtleArtActivity": {
 +
    "title": "Turtle Blocks",
 +
    "version": "202",
 +
    "blob": "http://download.sugarlabs.org/activities/4027/turtleblocks-202.xo",
 +
    "content-type": "application/vnd.olpc-sugar",
 +
    "size": 4715955,
 +
    "unpack_size": 12873871,
 +
    "command": "sugar-activity TurtleArtActivity.TurtleArtActivity",
 +
  },
 +
  "sugar": {
 +
    "version": "0.94",
 +
  },
 +
}
   −
: The particular resource properties were modified:
+
<div id="GET-clone"></div>
−
:* {{Code|type: update}}
     −
: The particular resource was deleted (hidden):
+
Like the [[#GET-solve|solve]] command, ''clone'' makes a solution but returns bundle itself, so, there is no way to get information about possible dependencies.
−
:* {{Code|type: delete}}
     −
== Resources ==
+
'''GET''' /context/''GUID''?cmd='''clone'''[&lsb_id=''LSB_ID''][&lsb_release=''LSB_RELEASE''][&assume=''DEPENDENCY''-''VERSION'']
   −
=== player ===
+
=== Upload releases ===
   −
Properties:
+
To easy upload Context [[#context-releases|releases]] and avoid writing to raw ''Context.releases'' property, there is a special high-level API command.
−
:* {{Code|nickname}}, ''str'', ''read''<br>set by Sugar Shell;
  −
:* {{Code|color}}, ''str'', ''read''<br>colors pair in format {{Code|#RRGGBB,#RRGGBB}}, set by Sugar Shell.
     −
Calculated properties:
+
'''POST''' /context?cmd='''submit'''[&''PROP''=''VALUE''][&initial]
−
:* {{Code|reputation}}, ''int'', ''read''<br>current ''player'''s reputation based on:
  −
:** direct votes from other players,
  −
:** votes given to objects where the ''player'' is a creator;
  −
:* {{Code|vote}}, ''bool'', ''read'', ''write''<br>did url requester voted for the current object or not;
     −
Actions:
+
Where the {{Code|PROP}} arguments are optional release properties. The {{Code|initial}} argument asks the system to create new Context resource new release will belong to.
   −
* ''player'' cannot be created or destroyed;
+
The posting data might be two types,
−
* ''player'' can be updated only by a user who is associated with it.
     −
POST /player/<GUID>/'''send'''
+
* Sugar activities in .xo bundles,<br>there is no need in {{Code|PROP}} arguments, all properties will be populated basing on metadata from a .xo bundle; including release notes from the {{Code|CHANGELOG}} file in [[Wikipedia:Markdown|Markdown]] notation; besides, only in this case {{Code|initial}} makes sense because it is the only way to get Context properties;
   −
Send private message to the ''player''.
+
* Arbitrary data,<br>all required release properties should be specified in {{Code|PROP}} arguments, at least ''context'' and ''version''; ''license'' should be specified only if there are no existing releases to pickup license from.
   −
Sends:
+
=== Node statistics ===
−
: A dictionary with [[#event|event]] properties.
     −
Events:
+
The node statistics are about the entire server and depersonalized. Statistics are being collected by analyzing regular requests to an API server and stored for each Sugar Network node. To read such info, call the command:
−
: Direct event to the ''player'':
  −
:* {{Code|type: message}}.
     −
=== project ===
+
'''GET''' /?cmd='''stats'''[&start=''SECONDS''][&end=''SECONDS''][&event=''EVENT''][&limit=''NUMBER'']
   −
Properties:
+
Where:
−
:* {{Code|title}}, ''str'', ''read'', ''write'' only for the team members<br>one line title;
  −
description;
  −
:* {{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|general}},
  −
:** {{Code|activity}},
  −
:** {{Code|wiki}},
  −
:** {{Code|gallery}};
  −
:* {{Code|zoom}}, ''str'', ''read'', ''write'' only for the team members<br>Network Zoom level that project belongs:
  −
:** {{Code|worldwide}},
  −
:** {{Code|neighbourhood}},
  −
:** {{Code|private}}.
     −
Calculated properties:
+
* {{Code|start}} and {{Code|end}} is a time interval to get statistics for; if omitted, the beginning and the end of entire life cycle will be used;
−
:* {{Code|reputation}}, ''int'', ''read''<br>current ''project'''s reputation based on:
+
* {{Code|event}}, multiple argument to specify what stats should be returned; if omitted, return all sources;
−
:** direct votes from other players,
+
* {{Code|limit}}, number of stat records to return for the {{Code|start}}-{{Code|end}} interval; note that this amount is not precise, the final resultset might be smaller or bigger depending on chosen resolution; stats resolution depends on node configuration, default values are 1 day, 10 days, 30 days, 365 days; if omitted, return {{Code|end}} record only.
−
:** votes given to related objects if theirs ''respect'' property is empty;
  −
:* {{Code|vote}}, ''bool'', ''read'', ''write''<br>did url requester voted for the current object or not.
     −
Many-to-many relations:
+
Possible events are:
−
:* ''team'', relates to ''player''.
     −
Actions:
+
* {{Code|users}}, total number of existing ''User'' objects;
 +
* {{Code|contexts}}, total number of existing ''Context'' objects;
 +
* {{Code|released}}, average number of newly uploaded ''Context.releases'' for specified time frame;
 +
* {{Code|solved}}, average number of requested ''Context'' [[#GET-solve|solutions]] for specified time frame; note that this value does not equal to the number of solution usages on client side since solutions might be cached;
 +
* {{Code|reported}}, average number of newly uploaded failure ''Report'' objects for specified time frame;
 +
* {{Code|topics}}, total number of top-level ''Post'' objects;
 +
* {{Code|posts}}, total number of dependent ''Post'' objects.
   −
* right after creation, the creator will be the only ''team'' member;
+
== Client API ==
−
* update and delete actions are allowed only for ''team'' members;
  −
* [[#Wiki_actions|Wiki related actions]] to manage object description.
     −
POST /project/<GUID/'''add_member'''?member=<PLAYER>
+
The reasons to proxy Sugar Network data on users side:
   −
Make a ''PLAYER'' the ''team'' member. Only ''team'' members can call this action.
+
* Seamless support [[#Offline mode|offline workflow]];
 +
* [[#Launching|One-click launch]] Sugar activities hosted on Sugar Network.
   −
Events:
+
Proxying happens by providing the same Sugar Network API (with some extra functionality, see below) from
−
:* {{Code|type: add_member}};
+
[[Platform_Team/Sugar_Network/Implementation#sugar-network-client|local process]] launched beforehand.
−
:* {{Code|memeber: GUID}}.
     −
POST /project/GUID/'''remove_member'''?member=<PLAYER>
+
=== Offline mode ===
   −
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''.
+
Being connected to a Sugar Network node, local proxy provides [[#Node_API|original API]] from the node. If the connection is lost, the proxy will switch to local Sugar Network storage and continue working providing only [[#Base_API|base API]]. Any content created in offline mode will be uploaded to the node after getting a connection back.
   −
Events:
+
Besides, local Sugar Network storage will be reused to keep users preferences, such as:
−
:* {{Code|type: remove_member}};
  −
:* {{Code|memeber: GUID}}.
     −
=== question ===
+
* Favorited Contexts<br>to select preferred ''Context'' resources; these Contexts will be marked by {{Code|favorite}} value in the ''Context.layer'' property;
   −
Properties:
+
* Checked-in Contexts<br>to keep most recent Context (for ''activity'' and ''book'' types) version in local storage to make it available in offline; note that there is no need in checking-in to speedup online lunch, versions are being [[#Launching|cached]] anyway; these Contexts will be marked by {{Code|checkin}} value in the ''Context.layer'' property.
−
:* {{Code|title}}, ''str'', ''read'', ''write'' only for creator<br>one line title;
  −
:* {{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|solution}}, ''guid'', ''read'', ''write'' only by creator<br>the ''solution'' which solves the object.
     −
Calculated properties:
+
To control users preferences there are special API commands:
−
:* {{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|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:
+
<div id="PUT_favorite"></div>
−
* [[#Wiki_actions|Wiki related actions]] to manage object description.
     −
=== idea ===
+
'''PUT''' /context/''GUID''?cmd='''favorite'''
   −
Properties:
+
Set favorite status.
−
:* {{Code|title}}, ''str'', ''read'', ''write'' only for creator<br>one line title;
  −
:* {{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.
     −
Calculated properties:
+
<div id="DELETE_favorite"></div>
−
:* {{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|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:
+
'''DELETE''' /context/''GUID''?cmd='''favorite'''
−
* [[#Wiki_actions|Wiki related actions]] to manage object description.
     −
=== problem ===
+
Unset favorite status.
   −
Properties:
+
<div id="PUT_checkin"></div>
−
:* {{Code|title}}, ''str'', ''read'', ''write'' only for creator<br>one line title;
  −
:* {{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|solution}}, ''guid'', ''read'', ''write'' only by creator<br>the ''solution'' which solves the object.
     −
Calculated properties:
+
'''PUT''' /context/''GUID''?cmd='''checkin'''[&spawn]
−
:* {{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|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:
+
Check-in the specified Context. By default, the command will return streamed ''text/event-stream'' MIME type data to monitor the progress. If the {{Code|spawn}} argument is specified, the command will exit immediately with [[#Notifications|asynchronous sending]] progress events.
−
* [[#Wiki_actions|Wiki related actions]] to manage object description.
     −
=== solution ===
+
<div id="DELETE_checkin"></div>
   −
The solution for ''question''/''idea''/''problem'' objects.
+
'''DELETE''' /context/''GUID''?cmd='''checkin'''
   −
Properties:
+
Checkout the Context.
−
:* {{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.
     −
Calculated properties:
+
=== Launching ===
−
:* {{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.
     −
Actions:
+
Sugar Network Contexts (for ''activity'' and ''book'' types) can be launched as-is. The launching process is implicit and includes selecting the most recent (and appropriate for software contexts) version, downloading bundles from the Sugar Network, installing missed [[Sugar_Network/Recipe_Specification#Dependencies|software dependencies]], execution itself. All downloaded bundles will be cached [with further garbage collecting] to speedup further launching.
−
* [[#Wiki_actions|Wiki related actions]] to manage object description.
     −
=== wiki ===
+
Sugar activities will be directly executed. Book Contexts will be opened in the proper application according to its MIME type.
   −
Properties:
+
'''GET''' /context/''GUID''?cmd='''launch'''[&args=''ARG''][&activity_id=''ACTIVITY_ID''][&object_id=''OBJECT_ID''][&uri=''URI''][&app=''APP''][&spawn]
−
:* {{Code|title}}, ''str'', ''read'', ''write'' only for creator<br>one line title;
  −
:* {{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|reputation}}, ''int'', ''read''<br>current object's reputation;
  −
:* {{Code|vote}}, ''bool'', ''read'', ''write''<br>did url requester voted for the current object or not;
     −
Actions:
+
Arguments that make sense only for Sugar activities:
−
* [[#Wiki_actions|Wiki related actions]] to manage Wiki page.
     −
=== gallery ===
+
* {{Code|ARG}}, command line argument to pass to launched activities, repeat {{Code|ARG}} for each argument;
 +
* {{Code|ACTIVITY_ID}}, internal activity id which will be auto set if omitted;
 +
* {{Code|OBJECT_ID}}, Journal object id to resume;
 +
* {{Code|URI}}, URL to resume if activity supports this functionality.
   −
Properties:
+
Arguments that make sense only for books:
−
:* {{Code|title}}, ''str'', ''read'', ''write'' only for creator<br>one line title;
  −
:* {{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|reputation}}, ''int'', ''read''<br>current object's reputation;
  −
:* {{Code|vote}}, ''bool'', ''read'', ''write''<br>did url requester voted for the current object or not;
     −
Actions:
+
* {{Code|APP}}, specify application Context to open the book by; if omitted, the system will try to find most appropriate option, among all existing software Contexts.
−
* [[#Wiki_actions|Wiki related actions]] to manage object description.
     −
GET /gallery/<GUID>/'''exhibit'''
+
Common arguments:
   −
Get the attached object.
+
* {{Code|spawn}}, by default, the command will return streamed ''text/event-stream'' MIME type data to monitor the whole launching process until exiting the application; if the {{Code|spawn}} argument is specified, the command will exit immediately with [[#Notifications|asynchronous sending]] launching events.
   −
Receives:
+
== Experimental API ==
−
: Attached object content with application/octet-stream MIME type.
     −
PUT /<RESOURCE>/<GUID>/'''exhibit'''
+
There is no guaranty that the following API will be stated as stable or frozen sometime.
   −
Put new attached object. Only object creator can use it.
+
=== Access to Sugar Journal ===
   −
Sends:
+
It is possible to get access to local Sugar Journal using special, ''journal'', resource provided from [[#Client_API|client API]]. This kind of access might be useful when local applications cannot use DBus sugar-datastore API, e.g., [[wikipedia:Javascript|Javascript]] applications. API to Journal is restricted only to read-only access:
−
: Attached object content with application/octet-stream MIME type.
     −
Events:
+
'''GET''' /journal?offset=''INTEGER''&limit=''INTEGER''[&query=''STRING''][&order_by=<nowiki>[+|-]</nowiki>''PROP''][&''QUERY_PROP''=''VALUE''[&...]]
−
: {{Code|type: update}}
+
'''GET''' /journal/''JOURNAL_ID''[?reply=''PROP''[,..]]
 +
'''GET''' /journal/''JOURNAL_ID''/''PROPERTY''
   −
=== objective ===
+
== Usage ==
   −
Properties:
+
Being HTTP based, Sugar Network API can be used in any manner regular HTTP requests can be handled. But for command-line access, there is a handy tool, {{Code|sugar-network}}, which takes care about Sugar Network specific like launching local API (if it is not already available) to get access to [[#Client_API|local proxy]].
−
:* {{Code|title}}, ''str'', ''read'', ''write'' only for the team members<br>one line title;
  −
:* {{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|reputation}}, ''int'', ''read''<br>current object's reputation;
  −
:* {{Code|vote}}, ''bool'', ''read'', ''write''<br>did url requester voted for the current object or not;
     −
Actions:
+
The sugar-network command-line format is below. Call {{Code|sugar-network --help}} for more detailed info.
−
* [[#Wiki_actions|Wiki related actions]] to manage object description.
     −
=== release ===
+
sugar-network GET|POST|PUT|DELETE ''PATH'' ''ARG=VALUE'' [..]
   −
=== comment ===
+
* {{Code|PATH}}, is an url path;
 +
* {{Code|ARG<nowiki>=</nowiki>VALUE}}, request arguments as they being passed to in url.
   −
=== event ===
+
{{Code|POST}} and {{Code|PUT}} commands require data to pass, use the following command-line arguments:
   −
== Changelog ==
+
* {{Code|-f FILE}} to specify the file to pass;
 +
* {{Code|-d DATA}} to specify string to pass;
 +
* {{Code|-j}} posted data should be encoded into JSON before posting.
   −
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.
+
== Getting involved ==
   −
'''1.0'''
+
{{:Sugar_Network/Feedback}}
−
: Not yet released API.
 
Retrieved from "https://wiki.sugarlabs.org/go/Special:MobileDiff/73426...93401"