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 203:
Line 216: − + − + − + Line 237:
Line 250: − While working, Sugar Network servers collect depersonalized and common [[Sugar_Network/Node_Statistics|statistics]]. To read such info, call the command:+ − + − * {{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, 365 days; − + + + + + + + + + + + +
→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_API|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>
"org.laptop.TurtleArtActivity": {
"org.laptop.TurtleArtActivity": {
"title": "Turtle Blocks",
"title": "Turtle Blocks",
"version": [[202], 0],
"version": "202",
"blob": "http://download.sugarlabs.org/activities/4027/turtleblocks-202.xo",
"blob": "http://download.sugarlabs.org/activities/4027/turtleblocks-202.xo",
"content-type": "application/vnd.olpc-sugar",
"content-type": "application/vnd.olpc-sugar",
"size": 4715955,
"size": 4715955,
"unpack_size": 12873871,
"unpack_size": 12873871,
"command": ["activity", "sugar-activity TurtleArtActivity.TurtleArtActivity"],
"command": "sugar-activity TurtleArtActivity.TurtleArtActivity",
},
},
"sugar": {
"sugar": {
"version": [[0, 94], 0],
"version": "0.94",
},
},
}
}
=== 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'''&records=''NUMBER''[&start=''SECONDS''][&end=''SECONDS''][&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; if omitted, the beginning and the end of entire life cycle will be used;
* {{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|source}}, multiple argument to specify what [[Sugar_Network/Node_Statistics#Common_statistics|stats]] should be returned; if omitted, return all sources.
* {{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.
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 ==