8,288
edits
Changes
no edit summary
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]].
== 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 [[Platform_Team/Sugar_Network/Objects_model|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. Resources might support [[#Common_actions|common actions]]. While processing requests, the server might 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 RESTful 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|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 [[#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.
== API servers ==
== API servers ==
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 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);
* [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;
* [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;
=== Authentication ===
=== 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]].
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''
''TODO''
=== Authorization ===
=== 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.
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 [[#Sugar_Network_resources|author]] property and can be modified using the following commands.
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''
'''PUT''' /''RESOURCE''/''GUID''?cmd='''useradd'''&user=''USER''&role=''ROLE''
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.
'''PUT''' /''RESOURCE''/''GUID''
'''PUT''' /''RESOURCE''/''GUID''
'''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''[&...]]
'''GET''' /''RESOURCE''[?offset=''INTEGER''][&limit=''INTEGER''][&query=''STRING''][&reply=''PROP''[,..]][&order_by=<nowiki>[+|-]</nowiki>''PROP''][&group_by=''PROP''][&''QUERY_PROP''=''VALUE''[&...]]
** 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;
** 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|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|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>coma separated list of ''RESOURCE'' properties to return; by default, return only {{Code|guid}} property;
* {{Code|reply}}, ''str''<br>comma 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.
'''GET''' /''RESOURCE''/''GUID''[?reply=''PROP''[,..]]
'''GET''' /''RESOURCE''/''GUID''[?reply=''PROP''[,..]]
Return properties for particular resource object.
Return properties for a particular resource object.
JSON object keys to receive:
JSON object keys to receive:
=== Download activities ===
=== Download activities ===
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).
To download a Sugar Activity bundle from the Sugar Network, it is required to find out the GUID of ''Implementation'' with the required 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'',..]
'''GET''' /context/''GUID''?cmd='''clone'''[&version=''VERSION''][&stability=''STABILITY''][&requires=''REQUIRES'',..]
* {{Code|VERSION}}<br>Version to download; if omitted, most recent will be used;
* {{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|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.
* {{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 used for processing dependencies while launching, ''requires'' property exists only to simplify user-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 on what Sugar version is required.
=== Notifications ===
=== Notifications ===
=== Node statistics ===
=== Node statistics ===
While working, Sugar Network servers collect unpersonalized and common [[Platform_Team/Sugar_Network_Statistics|statistics]]. To read such info, call the command:
While working, Sugar Network servers collect depersonalized and common [[Platform_Team/Sugar_Network_Statistics|statistics]]. To read such info, call the command:
'''GET''' /?cmd='''stats'''&start=''SECONDS''&end=''SECONDS''&resolution=''SECONDS''&source=''STATS-NAME''
'''GET''' /?cmd='''stats'''&start=''SECONDS''&end=''SECONDS''&resolution=''SECONDS''&source=''STATS-NAME''
=== Usage statistics ===
=== 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.
In order to collect [[Platform_Team/Usage_Statistics|usage statistics]] gathered in local users' environment by [[Platform_Team/Server_Kit/sugar-client|sugar-client]], the API provides related commands for ''User'' [[Sugar Network]] resource.
'''GET''' /user/''GUID''?cmd='''stats-info'''
'''GET''' /user/''GUID''?cmd='''stats-info'''
=== Offline case ===
=== Offline case ===
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 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.
=== Cloned resources ===
=== Cloned resources ===
Cloning is available only for the following resources:
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 equal to ''activity''<br>most recent activity ''Implementation'' will be placed in the {{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;
* ''Context'' with ''type'' property equal to ''content''<br>most recent content ''Implementation'' will be stored in Sugar Journal;
* ''Artifact'' resources<br>artifact will be stored in Sugar Journal.
* ''Artifact'' resources<br>artifact will be stored in Sugar Journal.
* {{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;
* {{Code|COLOR}}, comma separated pair of Sugar colors to assign to activity object;
* {{Code|NO_SPAWN}}, if specified, HTTP connection will not be closed until exiting activity process.
* {{Code|NO_SPAWN}}, if specified, HTTP connection will not be closed until exiting activity process.
== 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}}, that takes care about Sugar Network specific like launching local API (if it is not already available) to get access to [[#Client_proxy|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, pass the following command-line arguments:
* {{Code|-f FILE}} to specify the file to pass;
* {{Code|-f FILE}} to specify the file to pass;