5,705
edits
Changes
Jump to navigation
Jump to search
Line 5:
Line 5: − + − + − + Line 16:
Line 16: − + Line 22:
Line 22: − + − + − 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-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.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.+ − == Sugar Network resources ==+ − + − {{:Sugar_Network/Resources}} − This is an API provided by Sugar Network nodes.+ − === 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]].+ − ''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'' − + − + Line 106:
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 130:
Line 111: + + + + + + Line 143:
Line 130: − + Line 163:
Line 150: − + − + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + − + Line 175:
Line 200: − * {{Code|DEPENDENCY}}, solved release should conform the specified [[Sugar_Network/Recipe_Specification#Dependencies|dependencies]]; the argument might be multiple; − + + − + − + − '''GET''' /context/''GUID''?cmd='''resolve'''[&requires=''DEPENDENCY''][&lsb_id=''LSB_ID''][&lsb_release=''LSB_RELEASE''] + + + + + + + + + + + + + + − + + + + + − + Line 206:
Line 248: − + − − It is possible to subscribe to server events. Notification will happen using HTML5 [[wikipedia:Server-sent_events|Server-sent events]] (SSE). − + − + − 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 statistics === − − While working, Sugar Network servers collect depersonalized and common [[Sugar_Network/Node_Statistics|statistics]]. To read such info, call the command: − '''GET''' /?cmd='''stats'''&start=''SECONDS''&end=''SECONDS''&records=''NUMBER''&source=''STATS-NAME''+ + + − Where:+ − + − + − + + + + + − + Line 242:
Line 282: − + Line 298:
Line 338: − <!-- − === 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. − --> − +
→Base API
== Overview ==
== Overview ==
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.
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]], which are collections of objects. All objects are identified by globally unique identifiers, GUIDs. Resources might support [[#Common_actions|common actions]]. While processing requests, the 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 is 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|ARGUMENT}}s and {{Code|VALUE}}s depend on the particular [[#Actions|action]].
* {{Code|ARGUMENT}}s and {{Code|VALUE}}s depend on the particular [[#Actions|action]].
In [[#Common_actions|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 ==
== 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}}
=== Common actions ===
== Base API ==
List of actions common of all resources.
List of actions common of all API providers.
<div id="POST"></div>
<div id="POST"></div>
* {{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>
=== Aggregated properties ===
=== Aggregated properties ===
[[Sugar_Network/Resources#Property_types|Aggregated]] properties have special API to treat their content.
[[#resource-types|Aggregated]] properties have special API to treat their content.
<div id="POST-aggproperty"></div>
<div id="POST-aggproperty"></div>
Delete existing aggregated item. Depending on particular property, the command is allowed either to object's authors or to aggregated item submitter.
Delete existing aggregated item. Depending on particular property, the command is allowed either to object's authors or to aggregated item submitter.
=== Download releases ===
=== Notifications ===
To easy download Context [[Sugar_Network/Resources#context-releases|releases]] and avoid reading raw ''Context.releases'' property, there are special high-level API commands.
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''
=== 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>
<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|blob}}, bundle [[Sugar_Network/Resources#Property_types|digest]] to download;
* {{Code|blob}}, bundle [[#resource-types|digest]] to download;
* {{Code|version}}, chosen version number;
* {{Code|version}}, chosen version number;
* {{Code|title}}, the ''Context.title'' value;
* {{Code|title}}, the ''Context.title'' value;
* {{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 ===
To easy upload Context [[Sugar_Network/Resources#context-releases|releases]] and avoid writing to raw ''Context.releases'' property, there is a special high-level API command.
To easy upload Context [[#context-releases|releases]] and avoid writing to raw ''Context.releases'' property, there is a special high-level API command.
'''POST''' /context?cmd='''submit'''[&''PROP''=''VALUE''][&initial]
'''POST''' /context?cmd='''submit'''[&''PROP''=''VALUE''][&initial]
* 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.
* 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.
=== Notifications ===
=== Node statistics ===
To start subscription, send the following request:
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='''subscribe'''
'''GET''' /?cmd='''stats'''[&start=''SECONDS''][&end=''SECONDS''][&event=''EVENT''][&limit=''NUMBER'']
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|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|start}} and {{Code|end}} is a time interval to get statistics for;
* {{Code|users}}, total number of existing ''User'' objects;
* {{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|contexts}}, total number of existing ''Context'' objects;
* {{Code|source}}, multiple argument to specify what [[Sugar_Network/Node_Statistics#Common_statistics|stats]] should be returned.
* {{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 proxy ==
== Client API ==
The reasons to proxy Sugar Network data on users side:
The reasons to proxy Sugar Network data on users side:
=== Offline mode ===
=== Offline mode ===
Being connected to a Sugar Network server, local proxy provides original Sugar Network content. If the connection is lost, the proxy will switch to local Sugar Network storage and continue working. Any content created in offline mode will be uploaded to the server after getting a 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:
Besides, local Sugar Network storage will be reused to keep users preferences, such as:
* {{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.
* {{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 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.