Sugar Network/API - Revision history

Alsroot: /* Base API */

2014-09-27T12:56:08Z

Base API

← Older revision		Revision as of 08:56, 27 September 2014
Line 89:		Line 89:
	* {{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'']}};
	** 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;
	* {{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;

Alsroot: /* Sugar Network resources */

2014-07-24T04:12:33Z

Sugar Network resources

← Older revision		Revision as of 00:12, 24 July 2014
Line 45:		Line 45:
	* [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''.		* [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}}

Alsroot: /* API servers */

2014-07-24T04:11:57Z

API servers

← Older revision		Revision as of 00:11, 24 July 2014
Line 33:		Line 33:
	* ''0.2'' the most recent version, the rest of the document describes exactly this version.		* ''0.2'' the most recent version, the rest of the document describes exactly this version.

	== ~~API servers~~ ==		== Nodes ==

	These are standard Sugar Network API servers publicly available.		These are standard Sugar Network API servers publicly available.

Alsroot: /* API version */

2014-07-24T04:02:10Z

API version

← Older revision		Revision as of 00:02, 24 July 2014
Line 31:		Line 31:

	* ''0.1'' initial API implementation, should not be used;		* ''0.1'' initial API implementation, should not be used;
	* ''0.2.'' most recent version, the rest of the document describes exactly this ~~one~~.		* ''0.2'' the most recent version, the rest of the document describes exactly this version.

	== API servers ==		== API servers ==

Alsroot: /* API servers */

2014-07-24T04:01:21Z

API servers

← Older revision		Revision as of 00:01, 24 July 2014
Line 23:		Line 23:

	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 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.'' most recent version, the rest of the document describes exactly this one.

	== API servers ==		== API servers ==
Line 28:		Line 37:
	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 ==		== Sugar Network resources ==

Alsroot: /* Base API */

2014-06-04T11:59:51Z

Base API

← Older revision		Revision as of 07:59, 4 June 2014
Line 104:		Line 104:
	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>

Alsroot: /* Retrieving releases */

2014-05-24T15:56:37Z

Retrieving releases

← Older revision		Revision as of 11:56, 24 May 2014
Line 203:		Line 203:
	"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",
	},		},
	}		}

Alsroot: /* Node statistics */

2014-05-13T14:13:53Z

Node statistics

← Older revision		Revision as of 10:13, 13 May 2014
Line 244:		Line 244:

	* {{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\|event}}, 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.		* {{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.

Alsroot: /* Node statistics */

2014-05-13T14:10:25Z

Node statistics

← Older revision		Revision as of 10:10, 13 May 2014
Line 249:		Line 249:
	Possible events are:		Possible events are:

	* ~~'''~~users~~'''~~, total number of existing ''User'' objects;		* {{Code\|users}}, total number of existing ''User'' objects;
	* ~~'''~~contexts~~'''~~, total number of existing ''Context'' objects;		* {{Code\|contexts}}, total number of existing ''Context'' objects;
	* ~~'''~~released~~'''~~, average number of newly uploaded ''Context.releases'' for specified time frame;		* {{Code\|released}}, average number of newly uploaded ''Context.releases'' for specified time frame;
	* ~~'''~~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\|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;
	* ~~'''~~reported~~'''~~, average number of newly uploaded failure ''Report'' objects for specified time frame;		* {{Code\|reported}}, average number of newly uploaded failure ''Report'' objects for specified time frame;
	* ~~'''~~topics~~'''~~, total number of top-level ''Post'' objects;		* {{Code\|topics}}, total number of top-level ''Post'' objects;
	* ~~'''~~posts~~'''~~, total number of dependent ''Post'' objects.		* {{Code\|posts}}, total number of dependent ''Post'' objects.

	== Client API ==		== Client API ==

Alsroot: /* Node statistics */

2014-05-13T14:08:53Z

Node statistics

← Older revision		Revision as of 10:08, 13 May 2014
Line 237:		Line 237:
	=== Node statistics ===		=== Node statistics ===

	~~While working,~~ Sugar Network ~~servers collect depersonalized and common [[Sugar_Network/Node_Statistics\|statistics]]~~. To read such info, call the command:		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''][&event=''EVENT''][&limit=''NUMBER'']		'''GET''' /?cmd='''stats'''[&start=''SECONDS''][&end=''SECONDS''][&event=''EVENT''][&limit=''NUMBER'']
Line 246:		Line 246:
	* {{Code\|event}}, 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 [[Sugar_Network/Node_Statistics#Common_statistics\|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.		* {{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:

			* '''users''', total number of existing ''User'' objects;
			* '''contexts''', total number of existing ''Context'' objects;
			* '''released''', average number of newly uploaded ''Context.releases'' for specified time frame;
			* '''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;
			* '''reported''', average number of newly uploaded failure ''Report'' objects for specified time frame;
			* '''topics''', total number of top-level ''Post'' objects;
			* '''posts''', total number of dependent ''Post'' objects.

	== Client API ==		== Client API ==

← Older revision		Revision as of 08:56, 27 September 2014
Line 89:		Line 89:
	* {{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'']}};
	** 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;
	* {{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;

← Older revision		Revision as of 10:13, 13 May 2014
Line 244:		Line 244:

	* {{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\|event}}, 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.		* {{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.