5,705
edits
Changes
Jump to navigation
Jump to search
Line 1:
Line 1: − + + + − + − + − + Line 14:
Line 16: − + − + − + − + − 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 free for any experiments (administrative privileges for anonymous users);+ − + + − * [http://localhost:5001/ localhost:5001]<br>default url to get access to [[#Client_proxy|local proxy]] provided from user side application.+ − == Sugar Network resources ==+ − − {{:Platform_Team/Sugar_Network/Objects_model}} − − === Authentication === − − Right now, the only way to be authenticated on a Sugar Network server is running [[Platform_Team/Sugar_Network/Implementation#sugar-network-client|local application]] on client side and using the API it [[#Client_proxy|provides]]. − − ''TODO'' − − === Authorization === − Read-only access is available for anonymous requests, except special content like machine serial numbers. But to proceed any changes, clients need to be authenticated.+ − 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 [[#Sugar_Network_resources|author]] property and can be modified using the following commands.+ − '''PUT''' /''RESOURCE''/''GUID''?cmd='''useradd'''&user=''USER''&role=''ROLE''+ − 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.+ − '''PUT''' /''RESOURCE''/''GUID''?cmd='''userdel'''&user=''USER''+ − 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.+ − ''TODO''+ − === Common actions ===+ − List of actions common of all resources.+ Line 70:
Line 63: − + + + Line 78:
Line 73: + + − + − + + + − + − + − + − ** if property is boolean, integer or datetime, it supports searching by ranges: {{Code|''PROP'':[''START'']..[''END'']}};+ − + − + − − + − '''GET''' /''RESOURCE''/''GUID''[?reply=''PROP''[,..]]+ − + + + + + + + + + + + + + + Line 117:
Line 128: − + − To download Sugar Activity bundle from the Sugar Network, it is required to find out the GUID of ''Implementation'' with needed activity version. To make this process more convenient for users, there is special command that requires only ''Context'' GUID (which is, in most cases, equal to Sugar Activity bundle id).+ − '''GET''' /context/''GUID''?cmd='''clone'''[&version=''VERSION''][&stability=''STABILITY''][&requires=''REQUIRES'',..]+ − This command finds out required ''Implementation'', using passed parameters, and returns its bundle. Command parameters are:+ − * {{Code|VERSION}}<br>Version to download; if omitted, most recent will be used;+ − * {{Code|STABILITY}}<br>[[#Sugar_Network_resources|stability]] ''Implementation'' value; if omitted, ''stable'' will be used;+ − * {{Code|REQUIRES}}<br>while uploading new versions, system will keep dependency information in ''requires'' property of ''Implementations'' resources; it is not strict information and is not being used for processing dependencies while launching, ''requires'' property exists only to simplify users driven searching; {{Code|REQUIRES}} specifies ''requires'' property to search versions (option might be multiple); for the first time, the only guarantied ''requires'' values are {{Code|sugar-''VERSION''}} with information what Sugar version is required.+ + + + + + + + + + + Line 141:
Line 162: − + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + − While working, Sugar Network servers collect unpersonalized and common [[Platform_Team/Sugar_Network_Statistics|statistics]]. To read such info, call the command:+ − + − + − * {{Code|start}} and {{Code|end}} is a time interval to get statistics for;+ − * {{Code|resolution}}, number of seconds in one stats unit; − * {{Code|source}}, multiple argument to specify what [[Platform_Team/Sugar_Network_Statistics#Common_statistics|stats]] should be returned. − === Usage statistics ===+ − In order to collect [[Platform_Team/Usage_Statistics|usage statistics]] gathered in local users' environment by [[Platform_Team/Server_Kit/sugar-client|sugar-client]], API provides related commands for ''User'' [[Sugar Network]] resource.+ − '''GET''' /user/''GUID''?cmd='''stats-info'''+ − Returns a dictionary with RRD configuration settings for local stats collecting process that user side should use to avoid problems while uploading stats to the server.+ − + − Upload statistics. Request content should be in JSON notation and be a dictionary of:+ − + − + + − + + + + + + + + + + + − + − + − + − + − === Cloned resources ===+ − Sugar Network resources might be cloned to local storage to be available in offline and out of + − Sugar Network. − Cloning is available only for the following resources:+ − * ''Context'' with ''type'' property equals to ''activity''<br>most recent activity ''Implementation'' will be placed to {{Code|~/Activities}} directory; note that there is no need in cloning activities before starting, it is possible to [[#Launch_activities|launch]] them directly;+ − * ''Context'' with ''type'' property equals to ''content''<br>most recent content ''Implementation'' will be stored in Sugar Journal; − * ''Artifact'' resources<br>artifact will be stored in Sugar Journal. − To track what data is cloned, there are read-only resource properties that make sense only for API provided from the local process:+ − * {{Code|favorite}} ''bool''<br>resources bookmarked by local user; bookmarked [and cloned] activities will appear in Home View in Sugar Shell;+ − * {{Code|clone}} ''int''<br>cloning status: {{Code|0}}, not cloned; {{Code|1}}, cloning is in progress; {{Code|2}} resource is cloned. − To control cloned content, there are API commands:+ − '''PUT''' /''RESOURCE''/''GUID''?cmd='''favorite'''+ − Change favorite status. {{Code|PUT}} content should be favorite status.+ − '''PUT''' /''RESOURCE''/''GUID''?cmd='''clone'''[&force=1]+ − Change cloning status for the specified resource. {{Code|PUT}} content should be cloning status. If {{Code|force}} is passed, cloning will happen even if local copy already exists.+ − + − All activities can be launched as-is.+ − + + + + + + + + + + + + + + + − + − + − * {{Code|NO_SPAWN}}, if specified, HTTP connection will not be closed until exiting activity process.+ + + − Previously cloned activities will be launched as-is from {{Code|~/Activities}} directory. The rest of activities will be downloaded from the server and kept in cache directory [with further garbage collecting].+ − === Access to the Journal ===+ − + + + + + + + − − This kind of access might be useful when local applications cannot use DBus sugar-datastore API, e.g., [[wikipedia:Javascript|Javascript]] applications. − + − + Line 244:
Line 362: − +
→Base API
This page describes the API that Sugar Network clients use to interact with Sugar Network server. See also a guide to basic Sugar Network [[Sugar_Network/Concept|concepts]] and [[Platform_Team/Sugar_Network/Architecture|its twin page]] from technical point of view. Besides, visit the [[Sugar_Network|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 ==
To better understand this API, see technical explanation of the [[Platform_Team/Sugar_Network/Architecture#Conceptual_level|conceptual level]] and [[Platform_Team/Sugar_Network/Objects_model|objects model]] in particular.
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 operates with [[Sugar Network]] [[#Sugar_Network_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 [[#Notifications|events]].
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]].
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 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''..]]
http[s]://''SERVER''[/''RESOURCE''[/''GUID''[/''PROPERTY'']]][?[cmd=''COMMAND''][&''ARGUMENT''=''VALUE''..]]
* {{Code|SERVER}}, [[#API_servers|particular]] Sugar Network API server;
* {{Code|SERVER}}, [[#API_servers|particular]] Sugar Network API server;
* {{Code|RESOURCE}}, name one of the [[#Resources|existing]] resources;
* {{Code|RESOURCE}}, name one of the [[#Sugar_Network_resources|existing]] resources;
* {{Code|GUID}}, the {{Code|RESOURCE}}'s particular object;
* {{Code|GUID}}, the {{Code|RESOURCE}}'s particular object;
* {{Code|PROPERTY}}, particular property of {{Code|GUID}} 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|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 particular [[#Actions|action]].
* {{Code|ARGUMENT}}s and {{Code|VALUE}}s depend on the particular [[#Actions|action]].
In [[#Common_actions|most cases]], server replies in JSON notation. If request was failed, the replied JSON object will contain {{Code|request}} key, with original request, and {{Code|error}} key, with error message.
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 servers ==
== 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:
* [http://node-testing.sugarlabs.org/ node-testing.sugarlabs.org]<br>Recent stable release with data used in pilots; do not create temporal content here, use development server instead;
* ''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'';
* [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'';
* [http://node.sugarlabs.org/ node.sugarlabs.org]<br>Production server;
* [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''.
== Resources ==
{{:Sugar_Network/Resources}}
== Base API ==
List of actions common of all API providers.
<div id="POST"></div>
'''POST''' /''RESOURCE''
'''POST''' /''RESOURCE''
JSON object keys to receive:
JSON object keys to receive:
* {{Code|guid}}, with globally unique identifier that specifies created object.
* {{Code|guid}}, with globally unique identifier that specifies the created object.
<div id="PUT"></div>
'''PUT''' /''RESOURCE''/''GUID''
'''PUT''' /''RESOURCE''/''GUID''
JSON object keys to send:
JSON object keys to send:
* {{Code|RESOURCE}}'s properties to modify.
* {{Code|RESOURCE}}'s properties to modify.
<div id="DELETE"></div>
'''DELETE''' /''RESOURCE''/''GUID''
'''DELETE''' /''RESOURCE''/''GUID''
Delete 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 {{Code|GUID}} 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''[?offset=''INTEGER''][&limit=''INTEGER''][&query=''STRING''][&reply=''PROP''[,..]][&order_by=<nowiki>[+|-]</nowiki>''PROP''][&group_by=''PROP''][&''QUERY_PROP''=''VALUE''[&...]]
<div id="GET"></div>
'''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.
Find resource objects.
Where:
Where:
* {{Code|offset}}, ''int''<br>start index to return entries from;
* {{Code|offset}}, ''int''<br>start index to return entries from, the default value is {{Code|0}};
* {{Code|limit}}, ''int''<br>do not return more then specified value;
* {{Code|limit}}, ''int''<br>do not return more then specified value, maximal and default values are being setup on server side;
* {{Code|query}}, ''str''<br>search request in [http://xapian.org/docs/queryparser.html Xapian] notation with the following additions:
* {{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|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;
** the statement {{Code|''PROP''<nowiki>:=</nowiki>["]''VALUE''["]}} has the same effect as {{Code|QUERY_PROP}}; it is different to regular {{Code|''PROP'':''VALUE''}} where {{Code|VALUE}} might be a substring;
* {{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|QUERY_PROP}}, ''str''<br>supplements {{Code|query}} with filtering by exact value of the {{Code|QUERY_PROP}}; the resulting query string will be {{Code|''QUERY_PROP''<nowiki>=</nowiki>''VALUE'' AND (query)}};
* {{Code|reply}}, ''str''<br>''RESOURCE'' properties to return; by default, return only {{Code|guid}} property; argument is multiple;
* {{Code|reply}}, ''str''<br>coma separated list of ''RESOURCE'' properties to return; by default, return only {{Code|guid}} property;
* {{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|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.
* {{Code|group_by}}, ''str''<br>property name to group resulting list by.
JSON object keys to receive:
JSON object keys to receive:
* {{Code|total}}, total number in requested query (the reply might contain only portion restricted by {{Code|limit}} request argument);
* {{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.
* {{Code|result}}, an array of dictionaries with resource object properties, dictionaries contain at least {{Code|guid}} property.
<div id="GET-resource"></div>
Return properties for particular resource object.
'''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:
JSON object keys to receive:
* properties that were specified in {{Code|reply}} argument(s), at least {{Code|guid}}.
* 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''
'''GET''' /''RESOURCE''/''GUID''/''PROP''
* raw data or redirection for BLOB properties.
* raw data or redirection for BLOB properties.
=== Download activities ===
=== 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''
Update existing aggregated item. Depending on particular property, the command is allowed either to object's authors or to aggregated item submitter.
<div id="DELETE-aggproperty"></div>
'''DELETE''' /''RESOURCE''/''GUID''/''PROP''/''ID''
Delete existing aggregated item. Depending on particular property, the command is allowed either to object's authors or to aggregated item submitter.
=== Notifications ===
=== Notifications ===
* {{Code|event}}<br>event type.
* {{Code|event}}<br>event type.
=== Node statistics ===
== 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''
=== Authorization ===
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.
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.
'''PUT''' /''RESOURCE''/''GUID''?cmd='''useradd'''&user=''USER''&role=''ROLE''
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.
'''PUT''' /''RESOURCE''/''GUID''?cmd='''userdel'''&user=''USER''
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.
''TODO''
=== Retrieving releases ===
To easy download Context [[#context-releases|releases]] and avoid reading raw ''Context.releases'' property, there are special high-level API commands.
<div id="GET-solve"></div>
'''GET''' /context/''GUID''?cmd='''solve'''[&lsb_id=''LSB_ID''][&lsb_release=''LSB_RELEASE''][&assume=''DEPENDENCY''-''VERSION'']
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.
Solving requirements might be:
* {{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).
The resulting info is a JSON object with keys equal to Context guids and value objects for chosen release with the following keys:
* {{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.
For example, the {{Code|'''GET''' <nowiki>/context/org.laptop.TurtleArtActivity?cmd=solve&assume=sugar-0.94</nowiki>}} request returns:
{
"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",
},
}
<div id="GET-clone"></div>
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.
'''GET''' /context/''GUID''?cmd='''clone'''[&lsb_id=''LSB_ID''][&lsb_release=''LSB_RELEASE''][&assume=''DEPENDENCY''-''VERSION'']
=== Upload releases ===
To easy upload Context [[#context-releases|releases]] and avoid writing to raw ''Context.releases'' property, there is a special high-level API command.
'''GET''' /?cmd='''stats'''&start=''SECONDS''&end=''SECONDS''&resolution=''SECONDS''&source=''STATS-NAME''
'''POST''' /context?cmd='''submit'''[&''PROP''=''VALUE''][&initial]
Where:
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.
The posting data might be two types,
* 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;
* 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.
=== Node statistics ===
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:
'''POST''' /user/''GUID''?cmd='''stats-upload'''
'''GET''' /?cmd='''stats'''[&start=''SECONDS''][&end=''SECONDS''][&event=''EVENT''][&limit=''NUMBER'']
Where:
* {{Code|name}} name of RRD database to upload stats to;
* {{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|values}} an array of {{Code|timestamp, row}} tuples when {{Code|row}} is a dictionary of database field names and values.
* {{Code|event}}, multiple argument to specify what stats should be returned; if omitted, return all sources;
* {{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.
== Client proxy ==
Possible events are:
* {{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.
== Client API ==
The reasons to proxy Sugar Network data on users side:
The reasons to proxy Sugar Network data on users side:
* Seamless support offline workflow;
* Seamless support [[#Offline mode|offline workflow]];
* Provide user side features like cloning or launching software from the Sugar Network.
* [[#Launching|One-click launch]] Sugar activities hosted on Sugar Network.
Proxying happens by providing the same Sugar Network API (with some extra functionality, see below) from
Proxying happens by providing the same Sugar Network API (with some extra functionality, see below) from
[[Platform_Team/Sugar_Network/Implementation#sugar-network-client|local process]] launched beforehand.
[[Platform_Team/Sugar_Network/Implementation#sugar-network-client|local process]] launched beforehand.
=== Offline case ===
=== Offline mode ===
Being connected to a Sugar Network server, local proxy provides original Sugar Network content. If connections is lost, proxy will switch to local Sugar Network storage and continues working. Any content created in offline mode will be uploaded to the server after getting connection back.
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.
Besides, local Sugar Network storage will be reused to keep users preferences, such as:
* Favorited Contexts<br>to select preferred ''Context'' resources; these Contexts will be marked by {{Code|favorite}} value in the ''Context.layer'' property;
* 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.
To control users preferences there are special API commands:
<div id="PUT_favorite"></div>
'''PUT''' /context/''GUID''?cmd='''favorite'''
Set favorite status.
<div id="DELETE_favorite"></div>
'''DELETE''' /context/''GUID''?cmd='''favorite'''
Unset favorite status.
<div id="PUT_checkin"></div>
=== Launch activities ===
'''PUT''' /context/''GUID''?cmd='''checkin'''[&spawn]
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.
'''GET''' /context/''GUID''?cmd='''launch'''[&args=''ARG''][&activity_id=''ACTIVITY_ID''][&object_id=''OBJECT_ID''][&uri=''URI''][&color=''COLOR''][&no_spawn=''NO_SPAWN'']
<div id="DELETE_checkin"></div>
'''DELETE''' /context/''GUID''?cmd='''checkin'''
Checkout the Context.
=== Launching ===
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.
Sugar activities will be directly executed. Book Contexts will be opened in the proper application according to its MIME type.
'''GET''' /context/''GUID''?cmd='''launch'''[&args=''ARG''][&activity_id=''ACTIVITY_ID''][&object_id=''OBJECT_ID''][&uri=''URI''][&app=''APP''][&spawn]
Arguments that make sense only for Sugar activities:
* {{Code|ARG}}, command line argument to pass to launched activities, repeat {{Code|ARG}} for each argument;
* {{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|ACTIVITY_ID}}, internal activity id which will be auto set if omitted;
* {{Code|OBJECT_ID}}, Journal object id to resume;
* {{Code|OBJECT_ID}}, Journal object id to resume;
* {{Code|URI}}, URL to resume if activity supports this functionality;
* {{Code|URI}}, URL to resume if activity supports this functionality.
* {{Code|COLOR}}, coma separated pair of Sugar colors to assign to activity object;
Arguments that make sense only for books:
* {{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.
Common arguments:
* {{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.
It is possible to get access to local Sugar Journal using special, ''journal'', resource. API to Journal is restricted only to read-only access:
== Experimental API ==
There is no guaranty that the following API will be stated as stable or frozen sometime.
=== Access to Sugar Journal ===
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:
'''GET''' /journal?offset=''INTEGER''&limit=''INTEGER''[&query=''STRING''][&order_by=<nowiki>[+|-]</nowiki>''PROP''][&''QUERY_PROP''=''VALUE''[&...]]
'''GET''' /journal?offset=''INTEGER''&limit=''INTEGER''[&query=''STRING''][&order_by=<nowiki>[+|-]</nowiki>''PROP''][&''QUERY_PROP''=''VALUE''[&...]]
'''GET''' /journal/''JOURNAL_ID''[?reply=''PROP''[,..]]
'''GET''' /journal/''JOURNAL_ID''[?reply=''PROP''[,..]]
'''GET''' /journal/''JOURNAL_ID''/''PROPERTY''
'''GET''' /journal/''JOURNAL_ID''/''PROPERTY''
== Usage ==
== Usage ==
Being HTTP based, Sugar Network API can be used in any way how regular HTTP requests can be handled. But for command-line access, there is a handy tool, {{Code|sugar-network}}, that takes care about Sugar Network specific like lunching local API (if it is not already available) to get access to [[#Client_proxy|local proxy]].
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]].
The sugar-network command-line format is, call {{Code|sugar-network --help}} for more detailed info:
The sugar-network command-line format is below. Call {{Code|sugar-network --help}} for more detailed info.
sugar-network GET|POST|PUT|DELETE ''PATH'' ''ARG=VALUE'' [..]
sugar-network GET|POST|PUT|DELETE ''PATH'' ''ARG=VALUE'' [..]
* {{Code|ARG<nowiki>=</nowiki>VALUE}}, request arguments as they being passed to in url.
* {{Code|ARG<nowiki>=</nowiki>VALUE}}, request arguments as they being passed to in url.
{{Code|POST}} and {{Code|PUT}} commands requires data to pass, pass the following command-line arguments:
{{Code|POST}} and {{Code|PUT}} commands require data to pass, use the following command-line arguments:
* {{Code|-f FILE}} to specify the file to pass;
* {{Code|-f FILE}} to specify the file to pass;