5,705
edits
Changes
Jump to navigation
Jump to search
Line 24:
Line 24: − + + + + + + + + + + − + − + − + − + Line 80:
Line 89: − + − ** if property is boolean, integer or datetime, it supports searching by ranges: {{Code|''PROP'':[''START'']..[''END'']}}; − ** 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; Line 104:
Line 111: + + + + + + Line 155:
Line 168: − + Line 175:
Line 188: − + Line 181:
Line 194: − + Line 187:
Line 200: − * {{Code|DEPENDENCY}}, solved release should conform the specified [[Sugar_Network/Recipe_Specification#Dependencies|dependencies]]; the argument might be multiple; − + + Line 198:
Line 211: − + − '''GET''' /context/''GUID''?cmd='''resolve'''[&requires=''DEPENDENCY''][&lsb_id=''LSB_ID''][&lsb_release=''LSB_RELEASE''] + + + + + + + + + + + + + + − + + + + + Line 220:
Line 250: − While working, Sugar Network servers collect depersonalized and common [[Sugar_Network/Node_Statistics|statistics]]. To read such info, call the command:+ − + − + − + − + + + + + + + + + + + Line 313:
Line 353: − +
→Base API
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.
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:
* ''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.
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);
* [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;
* [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://node.sugarlabs.org/ node.sugarlabs.org]<br>Production server;
* [http://localhost:5001/ localhost:5001]<br>default url to get access to [[#Client_proxy|local proxy]] provided from user side application.
* [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''.
== Sugar Network resources ==
== Resources ==
{{:Sugar_Network/Resources}}
{{:Sugar_Network/Resources}}
* {{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, the default value is {{Code|0}};
* {{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, 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;
* {{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|!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|!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;
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>
<div id="GET-property"></div>
=== Authentication ===
=== 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_proxy|provides]].
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''
''TODO''
''TODO''
''TODO''
=== Download releases ===
=== Retrieving releases ===
To easy download Context [[#context-releases|releases]] and avoid reading raw ''Context.releases'' property, there are special high-level API commands.
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>
<div id="GET-solve"></div>
'''GET''' /context/''GUID''?cmd='''solve'''[&requires=''DEPENDENCY''][&lsb_id=''LSB_ID''][&lsb_release=''LSB_RELEASE'']
'''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.
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:
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_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|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:
The resulting info is a JSON object with keys equal to Context guids and value objects for chosen release with the following keys:
* {{Code|command}}, a command to launch the bundle, only for Sugar activities.
* {{Code|command}}, a command to launch the bundle, only for Sugar activities.
<div id="GET-resolve"></div>
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",
},
}
Like the [[#GET-solve|solve]] command, ''resolve'' makes a solution but returns bundle itself, i.e., it ignores possible dependencies.
<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 ===
=== Upload releases ===
=== Node statistics ===
=== 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:
'''GET''' /?cmd='''stats'''&start=''SECONDS''&end=''SECONDS''&records=''NUMBER''&source=''STATS-NAME''
'''GET''' /?cmd='''stats'''[&start=''SECONDS''][&end=''SECONDS''][&event=''EVENT''][&limit=''NUMBER'']
Where:
Where:
* {{Code|start}} and {{Code|end}} is a time interval to get statistics for;
* {{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|records}}, 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, 366 days;
* {{Code|event}}, multiple argument to specify what stats should be returned; if omitted, return all sources;
* {{Code|source}}, multiple argument to specify what [[Sugar_Network/Node_Statistics#Common_statistics|stats]] should be returned.
* {{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.
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 ==
== Client API ==
== Usage ==
== Usage ==
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_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 below. 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.