Difference between revisions of "Sugar Network/API"

From Sugar Labs
Jump to navigation Jump to search
 
(101 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
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]].
 +
 
 +
{{Note/warning|Note|Until announcing API freeze, this document describes the most recent development version of the API.<br>You can find its implementation on the [[#API servers|node-devel.sugarlabs.org]] server.}}
  
 
== 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 [[#Sugar_Network_resources|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]]. Besides, API provides [[#Additional_resources|extra resources]] that are not [[Sugar Network]] objects.
+
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 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 request url format is:
  
−
  http[s]://<SERVER>[/<RESOURCE>[/<GUID>[/<PROPERTY>]]][?[cmd=<COMMAND>][&<ARGUMENT>=<VALUE>..]]
+
  http[s]://''SERVER''[/''RESOURCE''[/''GUID''[/''PROPERTY'']]][?[cmd=''COMMAND''][&''ARGUMENT''=''VALUE''..]]
  
 
When:
 
When:
  
−
* {{Code|SERVER}}, particular Sugar Network API server, e.g., http://api-devel.network.sugarlabs.org;
+
* {{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|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 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;
  
−
If request needs to send data, it should send Python dictionary converted to [[Wikipedia:Json|JSON]] notation.
+
Currently available API versions:
  
−
In [[#Common_actions|most cases]], server replies with dictionary in JSON notation. If request was failed, the replied dictionary will contain {{Code|request}}, with original request, and {{Code|error}}, with error message, keys. In the rest of cases, response might be variable.
+
* ''0.1'' initial API implementation, should not be used;
 +
* ''0.2'' the most recent version, the rest of the document describes exactly this version.
  
−
== Sugar Network resources ==
+
== Nodes ==
  
−
{{:Platform_Team/Sugar_Network/Objects_model}}
+
These are standard Sugar Network API servers publicly available.
  
−
=== Authentication ===
+
* [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'';
  
−
Right now, the only way to be authenticated on a Sugar Network server is running {{Code|sugar-network-service}} on client side and use API it [[#Local_resources|provides]].
+
* [http://node.sugarlabs.org/ node.sugarlabs.org]<br>Production server;
  
−
''TODO''
+
* [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''.
  
−
=== Authorization ===
+
== Resources ==
  
−
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.
+
{{:Sugar_Network/Resources}}
  
−
''TODO''
+
== Base API ==
  
−
=== Common actions ===
+
List of actions common of all API providers.
  
−
List of actions common of all resources.
+
<div id="POST"></div>
  
−
  '''POST''' /<RESOURCE>
+
  '''POST''' /''RESOURCE''
  
 
Create new resource object.
 
Create new resource object.
  
−
Dictionary to send:
+
JSON object keys to send:
−
: {{Code|''RESOURCE}}'s properties.
+
* {{Code|''RESOURCE}}'s properties.
  
−
Dictionary 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>
+
<div id="PUT"></div>
 +
 
 +
  '''PUT''' /''RESOURCE''/''GUID''
  
 
Modify resource object. By default, might be called only by {{Code|GUID}} creator.
 
Modify resource object. By default, might be called only by {{Code|GUID}} creator.
  
−
Dictionary to send:
+
JSON object keys to send:
−
: {{Code|RESOURCE}}'s properties to modify.
+
* {{Code|RESOURCE}}'s properties to modify.
 +
 
 +
<div id="DELETE"></div>
 +
 
 +
'''DELETE''' /''RESOURCE''/''GUID''
  
−
'''DELETE''' /<RESOURCE>/<GUID>
+
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.
  
−
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.
+
<div id="GET"></div>
  
−
  '''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''][&''PROP''=''VALUE''][&''!PROP''=''VALUE'']
  
 
Find resource objects.
 
Find resource objects.
  
 
Where:
 
Where:
−
:* {{Code|offset}}, ''int''<br>start index to return entries from;
+
* {{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;
+
* {{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>]}};
+
* {{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;
−
:** the statement {{Code|<nowiki><PROP>:=["]<VALUE>["]</nowiki>}} means {{Code|(<THE-REST_QUERY>) AND <EXACT-PROP-SEARCH>}} with searching {{Code|PROP}} for exact {{Code|VALUE}}; it is different to regular {{Code|<PROP>:<VALUE>}} where {{Code|VALUE}} might be a substring of exact {{Code|PROP}} value;
+
* {{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|QUERY_PROP}}, ''str''<br>supplement {{Code|query}} with filtering by property value, the resulting query string will be {{Code|<nowiki>QUERY_PROP=VALUE AND (query)</nowiki>}};
+
* {{Code|reply}}, ''str''<br>''RESOURCE'' properties to return; by default, return only {{Code|guid}} property; argument is multiple;
−
:* {{Code|reply}}, ''str''<br>coma 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:
 +
* {{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.
 +
 
 +
<div id="GET-resource"></div>
 +
 
 +
'''GET''' /''RESOURCE''/''GUID''[?reply=''PROP'']
 +
 
 +
Where:
 +
* {{Code|reply}}, ''str''<br>''RESOURCE'' properties to return; by default, return only {{Code|guid}} property; argument is multiple;
  
−
Dictionary keys to receive:
+
Return properties for a particular resource object.
−
:* {{Code|total}}, total number in requested query (the reply might contain only portion restricted by {{Code|limit}} request argument);
 
−
:* {{Code|result}}, an array of dictionaries with resource object properties, dictionaries contain at least {{Code|guid}} property.
 
  
−
'''GET''' /<RESOURCE>/<GUID>[?reply=<PROP>[,..]]
+
JSON object keys to receive:
 +
* properties that were specified in {{Code|reply}} argument(s), at least {{Code|guid}}.
  
−
Return properties for particular resource object.
+
<div id="PUT-property"></div>
  
−
Dictionary keys to receive:
+
'''PUT''' /''RESOURCE''/''GUID''/''PROP''
−
:* properties that were specified in {{Code|reply}} argument(s), at least {{Code|guid}}.
 
  
−
  '''GET''' /<RESOURCE>/<GUID>/<PROPERTY>
+
Modify particular resource property. By default, might be called only by {{Code|GUID}} creator.
 +
 
 +
<div id="GET-property"></div>
 +
 
 +
  '''GET''' /''RESOURCE''/''GUID''/''PROP''
  
 
Return property value for particular resource object.
 
Return property value for particular resource object.
  
 
Data to receive:
 
Data to receive:
−
:* property value in JSON notation.
+
* property value in JSON notation for regular properties;
 +
* raw data or redirection for BLOB properties.
 +
 
 +
=== Aggregated properties ===
 +
 
 +
[[#resource-types|Aggregated]] properties have special API to treat their content.
 +
 
 +
<div id="POST-aggproperty"></div>
 +
 
 +
'''POST''' /''RESOURCE''/''GUID''/''PROP''
 +
 
 +
Submit new item. The command returns an id for newly created aggregated item. Depending on particular property, new items might be created not only by object's authors.
 +
 
 +
<div id="PUT-aggproperty"></div>
 +
 
 +
'''PUT''' /''RESOURCE''/''GUID''/''PROP''/''ID''
 +
 
 +
Update existing aggregated item. Depending on particular property, the command is allowed either to object's authors or to aggregated item submitter.
 +
 
 +
<div id="DELETE-aggproperty"></div>
 +
 
 +
'''DELETE''' /''RESOURCE''/''GUID''/''PROP''/''ID''
 +
 
 +
Delete existing aggregated item. Depending on particular property, the command is allowed either to object's authors or to aggregated item submitter.
  
 
=== Notifications ===
 
=== Notifications ===
  
−
It is possible to subscribe to server events. Notification will happen using HTML5 [[wikipedia:Server-sent_events|Server-sent events]].
+
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:
 
To start subscription, send the following request:
  
−
  '''GET''' /?cmd='''subscribe'''[&only_commits=1]
+
  '''GET''' /?cmd='''subscribe'''
−
 
 
−
Where:
 
−
* {{Code|only_commits}},<br>subscribers can be notified only with ''commit'' events; that is useful to minimize interactions between server and clients.
 
  
 
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:
 
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:
Line 113: Line 162:
 
* {{Code|event}}<br>event type.
 
* {{Code|event}}<br>event type.
  
−
=== Usage statistics ===
+
== Node API ==
  
−
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.
+
This is an API provided by Sugar Network nodes on top of [[#Base_API|base one]].
  
−
'''GET''' /user/''GUID''?cmd='''stats-info'''
+
=== Authentication ===
  
−
Returns a dictionary with RRD configuration settings for local stats collecting process that user side should use to avoid problems while uploading stats to the server.
+
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]].
  
−
  '''POST''' /user/''GUID''?cmd='''stats-upload'''
+
''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''
  
−
Upload statistics. Request content should be in JSON notation and be a dictionary of:
+
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.
  
−
* {{Code|name}} name of RRD database to upload stats to;
+
'''PUT''' /''RESOURCE''/''GUID''?cmd='''userdel'''&user=''USER''
−
* {{Code|values}} an array of {{Code|timestamp, row}} tuples when {{Code|row}} is a dictionary of database field names and values.
 
  
−
=== GNU/Linux packages metadata ===
+
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.
  
−
There is a special Project resource, ''Packages''. This project is intended to support a metadata ''database'' for all GNU/Linux packages that are being used as dependencies for activities Sugar Network provides.
+
''TODO''
  
−
Every entry in the ''Packages'' project is a map of native package names to a particular GNU/Linux distribution. So, activities mention only ''Packages'' entry name as a dependency. Afterwards, on a client side, a ''Packages'' entry name will be resolved to a package name according to the local distribution and it will be passed to the PackageKit to install corresponding dependency.
+
=== Retrieving releases ===
  
−
''Packages'' project might be considered as a temporal solution when, and if, [http://distributions.freedesktop.org/wiki/AppStream/MetadataNotes AppStream's MetadataNotes] will be reused in the future.
+
To easy download Context [[#context-releases|releases]] and avoid reading raw ''Context.releases'' property, there are special high-level API commands.
  
−
== Additional resources ==
+
<div id="GET-solve"></div>
  
−
In addition to direct Sugar Network [[#Resources|resources]], API provides related content.
+
'''GET''' /context/''GUID''?cmd='''solve'''[&lsb_id=''LSB_ID''][&lsb_release=''LSB_RELEASE''][&assume=''DEPENDENCY''-''VERSION'']
  
−
=== packagekit-backend-presolve ===
+
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.
  
−
In order to provide GNU/Linux-distribution-agnostic launches of activities, Sugar Network API supports [[Platform_Team/packagekit-backend-presolve|packagekit-backend-presolve]] users.
+
Solving requirements might be:
  
−
API server provides the following kinds of urls:
+
* {{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|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).
  
−
* {{Code|'''GET''' /packages}}<br>list all supported platforms;
+
The resulting info is a JSON object with keys equal to Context guids and value objects for chosen release with the following keys:
−
* {{Code|'''GET''' /packages/<PLATFORM>}}<br>list all supported packages for a particular platform;
+
 
−
* {{Code|'''GET''' /packages/<PLATFORM>/<PACKAGE>}}<br>pre-solved dependency graph for a particular package.
+
* {{Code|blob}}, bundle [[#resource-types|digest]] to download;
 +
* {{Code|version}}, chosen version number;
 +
* {{Code|title}}, the ''Context.title'' value;
 +
* {{Code|command}}, a command to launch the bundle, only for Sugar activities.
 +
 
 +
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",
 +
  },
 +
}
 +
 
 +
<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 ===
 +
 
 +
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]
 +
 
 +
Where the {{Code|PROP}} arguments are optional release properties. The {{Code|initial}} argument asks the system to create new Context resource new release will belong to.
 +
 
 +
The posting data might be two types,
 +
 
 +
* Sugar activities in .xo bundles,<br>there is no need in {{Code|PROP}} arguments, all properties will be populated basing on metadata from a .xo bundle; including release notes from the {{Code|CHANGELOG}} file in [[Wikipedia:Markdown|Markdown]] notation; besides, only in this case {{Code|initial}} makes sense because it is the only way to get Context properties;
 +
 
 +
* 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.
 +
 
 +
=== 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''][&event=''EVENT''][&limit=''NUMBER'']
  
 
Where:
 
Where:
  
−
* {{Code|PLATFORM}}<br>one of supported packagekit-backend-presolve platforms, e.g., OLPC-13.0.1;
+
* {{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|PACKAGE}}<br>a name of the particular package.
+
* {{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 ==
 +
 
 +
The reasons to proxy Sugar Network data on users side:
 +
 
 +
* Seamless support [[#Offline mode|offline workflow]];
 +
* [[#Launching|One-click launch]] Sugar activities hosted on Sugar Network.
 +
 
 +
Proxying happens by providing the same Sugar Network API (with some extra functionality, see below) from
 +
[[Platform_Team/Sugar_Network/Implementation#sugar-network-client|local process]] launched beforehand.
 +
 
 +
=== Offline mode ===
 +
 
 +
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:
 +
 
 +
* Favorited Contexts<br>to select preferred ''Context'' resources; these Contexts will be marked by {{Code|favorite}} value in the ''Context.layer'' property;
 +
 
 +
* Checked-in Contexts<br>to keep most recent Context (for ''activity'' and ''book'' types) version in local storage to make it available in offline; note that there is no need in checking-in to speedup online lunch, versions are being [[#Launching|cached]] anyway; these Contexts will be marked by {{Code|checkin}} value in the ''Context.layer'' property.
 +
 
 +
To control users preferences there are special API commands:
 +
 
 +
<div id="PUT_favorite"></div>
 +
 
 +
'''PUT''' /context/''GUID''?cmd='''favorite'''
 +
 
 +
Set favorite status.
 +
 
 +
<div id="DELETE_favorite"></div>
 +
 
 +
'''DELETE''' /context/''GUID''?cmd='''favorite'''
 +
 
 +
Unset favorite status.
 +
 
 +
<div id="PUT_checkin"></div>
 +
 
 +
'''PUT''' /context/''GUID''?cmd='''checkin'''[&spawn]
 +
 
 +
Check-in the specified Context. By default, the command will return streamed ''text/event-stream'' MIME type data to monitor the progress. If the {{Code|spawn}} argument is specified, the command will exit immediately with [[#Notifications|asynchronous sending]] progress events.
 +
 
 +
<div id="DELETE_checkin"></div>
 +
 
 +
'''DELETE''' /context/''GUID''?cmd='''checkin'''
 +
 
 +
Checkout the Context.
 +
 
 +
=== Launching ===
 +
 
 +
Sugar Network Contexts (for ''activity'' and ''book'' types) can be launched as-is. The launching process is implicit and includes selecting the most recent (and appropriate for software contexts) version, downloading bundles from the Sugar Network, installing missed [[Sugar_Network/Recipe_Specification#Dependencies|software dependencies]], execution itself. All downloaded bundles will be cached [with further garbage collecting] to speedup further launching.
 +
 
 +
Sugar activities will be directly executed. Book Contexts will be opened in the proper application according to its MIME type.
 +
 
 +
'''GET''' /context/''GUID''?cmd='''launch'''[&args=''ARG''][&activity_id=''ACTIVITY_ID''][&object_id=''OBJECT_ID''][&uri=''URI''][&app=''APP''][&spawn]
 +
 
 +
Arguments that make sense only for Sugar activities:
  
−
Using [[#GNU/Linux packages metadata|Packages]]' metadata, [[Sugar Network]] will automatically generate dependency graphs for packagekit-backend-presolve.
+
* {{Code|ARG}}, command line argument to pass to launched activities, repeat {{Code|ARG}} for each argument;
 +
* {{Code|ACTIVITY_ID}}, internal activity id which will be auto set if omitted;
 +
* {{Code|OBJECT_ID}}, Journal object id to resume;
 +
* {{Code|URI}}, URL to resume if activity supports this functionality.
  
−
== Local resources ==
+
Arguments that make sense only for books:
  
−
If [[#Sugar_Network_resources|already mentioned]] resources are being provided from a network server, it is possible to get access to localhost resources served using the same RESTful API by local process launched beforehand. Local Sugar Network resources are [[#Sugar_Network_resources|the same]] structure data but located on local host, e.g., in user's home directory or on mounted removable device.
+
* {{Code|APP}}, specify application Context to open the book by; if omitted, the system will try to find most appropriate option, among all existing software Contexts.
  
−
This kind of access might be useful when local applications cannot use regular IPC mechanisms, e.g., D-Bus, to get access to local resources. For example, local [[wikipedia:Javascript|Javascript]] applications.
+
Common arguments:
  
−
=== Mountpoints ===
+
* {{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.
  
−
To differentiate what particular Sugar Network source is needed, all requests should have {{Code|mountpoint}} argument which might be one of the following values:
+
== Experimental API ==
  
−
* {{Code|/}}, default mountpoint if argument was not specified; get access to remote resources, i.e., local API provider is a kind of proxy to the remote one;
+
There is no guaranty that the following API will be stated as stable or frozen sometime.
  
−
* {{Code|~}}, Sugar Network content located in {{Code|~/.sugar/''PROFILE''/network}} directory; this mountpoint might support special use cases, see the rest of this text;
+
=== Access to Sugar Journal ===
  
−
* {{Code|''PATH''}}, absolute path in local files system to a directory with Sugar Network content, e.g., it might be content on mounted disk, {{Code|/media/DISK}}.
+
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:
  
−
The mountpoint {{Code|/}}, in addition to proxing user requests to a Sugar Network server, provides the following functionality:
+
'''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''/''PROPERTY''
  
−
* user is already authenticated, e.g., it is possible to change content on Sugar Network server.
+
== Usage ==
  
−
There are the following mountpoints related commands:
+
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]].
  
−
'''GET''' /?cmd='''mounts'''
+
The sugar-network command-line format is below. Call {{Code|sugar-network --help}} for more detailed info.
  
−
Returns a list of all accessible mountpoints. List items are dictionaries with the following keys:
+
sugar-network GET|POST|PUT|DELETE ''PATH'' ''ARG=VALUE'' [..]
  
−
* {{Code|mountpoint}}, mountpoint;
+
* {{Code|PATH}}, is an url path;
−
* {{Code|name}}, i18n name of the mountpoint;
+
* {{Code|ARG<nowiki>=</nowiki>VALUE}}, request arguments as they being passed to in url.
−
* {{Code|private}}, boolean flag; {{Code|True}} if the mountpoint is accessible only from localhost.
 
  
−
<!--=== Access to the Journal ===
+
{{Code|POST}} and {{Code|PUT}} commands require data to pass, use the following command-line arguments:
  
−
It is possible to get access to local Sugar Journal using ''Artifact'' resources from {{Code|~}} mountpoint. All ''Artifact'' [[#Sugar_Network_resources|properties]] represent particular Journal entity attributes when arbitrary attributes, e.g., create by particular Sugar Activity, are being collected in {{Code|traits}} property. It is possible to work with local ''Artifact'' resources like any regular Sugar Network one, e.g., make a search.-->
+
* {{Code|-f FILE}} to specify the file to pass;
 +
* {{Code|-d DATA}} to specify string to pass;
 +
* {{Code|-j}} posted data should be encoded into JSON before posting.
  
 
== Getting involved ==
 
== Getting involved ==
  
 
{{:Sugar_Network/Feedback}}
 
{{:Sugar_Network/Feedback}}

Latest revision as of 07:56, 27 September 2014

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 concepts and its twin page for a technical point of view. In addition, visit the introduction page.

Warning.png
Note
Until announcing API freeze, this document describes the most recent development version of the API.
You can find its implementation on the node-devel.sugarlabs.org server.

Overview

To better understand this API, see a technical explanation of its conceptual level and objects model in particular.

The API operates with Sugar Network resources, which are collections of objects. All objects are identified by globally unique identifiers, GUIDs, and available for operation via basic actions. The API is being provided from a node server or a client. While processing requests, API providers generate events.

The API is RESTful, and is served via HTTP(S) using JSON notation. The common request url format is: 

http[s]://SERVER[/RESOURCE[/GUID[/PROPERTY]]][?[cmd=COMMAND][&ARGUMENT=VALUE..]]

When:

  • SERVER, particular Sugar Network API server;
  • RESOURCE, name one of the existing resources;
  • GUID, the RESOURCE's particular object;
  • PROPERTY, particular property of GUID object;
  • COMMAND, optional command name; combination of HTTP request method (GET, POST, PUT, or, DELETE) and [possibly empty] COMMAND composes the requested action;
  • ARGUMENTs and VALUEs depend on the particular action.

In most cases, the server replies in JSON notation. If a request fails, the replied JSON object will contain a request key, with the original request, and 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 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.

  • node-devel.sugarlabs.org
    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;
  • node-testing.sugarlabs.org
    Recent stable release with regular data import from the production server; is still free for any experiments; default API version is 0.1;

Resources

The following diagram shows the full list of objects implemented by the Sugar Network API.

Sugar Network objects

Property types

Generally, Sugar Network objects' property types correspond to JSON types. The only exceptions mentioned in the following list:

  • enum, is an enumerated type when a value is a string from the predefined list of constants;
  • markdown, is a string formatted in the Markdown syntax;
  • blob, is a file represented by string value which is a SHA-1 digest of file's content; the file itself can be obtained from the GET /blobs/DIGEST request;
  • aggregated, is a list of JSON objects which has special API to treat its items; each aggregated item has a unique identifier; items might be created not only by the object's authors.

Resource.author

A dictionary of authors working on the corresponding resource. Keys are Sugar Network User guids, or, if particular author is not registered in the Sugar Network, full user names. Values are dictionaries with the following keys:

  • name
    Full author's name;
  • role
    An integer which is a bit-wise ORed value of the following constants:
    • 0x1, author is registered in the Sugar Network (and guid key is set);
    • 0x10000, author is the original author of the corresponding resource; if it is not set, user is only a maintainer, e.g., an uploader of a book which has its original authors;
  • avatar
    An url to author's avatar.

Resource.status

This is a system level property which can be set only by node editors. It is a list of "badges" editors set depending on the object quality. Currently supported statuses are:

  • featured, the object is popped up by node editors.

Resource.pins

This property makes sense only for objects provided from a local proxy. The property is intended to store local user's preferences or statuses remote object has in local environment. Currently supported values are:

  • favorite, set if a user has "stared" the object;
  • checkin, applied to Context objects only, set if a user has "pinned" the context to keep its most recent version permanently in the local system;
  • stale, applied to Context objects only, set if previously checked-in Context might have more fresh releases on the node; it is not possible to filter Contexts by this value;
  • inprogress, applied to Context objects only, set if the Context is in the process of downloading content from the node; it is being temporally set before launching the Context or checking it in; it is not possible to filter Contexts by this value.

Context.type

  • activity, Sugar application;
  • book, books in various forms;
  • group, a social group of related activities;
  • talks, sub-type to mix-in offline discussion forum;
  • project, sub-type to mix-in issue tracker and polling functionality.

Context type specifies how context, and all related resources, can be used. For example, activity type assumes activity bundles uploaded to the Context.releases property, or, Post.type depends on Context type it was created for.

Context.releases

Contexts with activity or book types might have releases, i.e., activity or book versions that users can download. The releases property is aggregated where each item describes one particular version. There is no need in working with the releases property directly, there are high-level API commands to upload and download releases.

Post.type

Choose Post types according to Context types the Post belongs to.

  • topic, general purpose discussion; talks Contexts;
  • artefact, object generated by Context application; activity Contexts;
  • issue, problem with the Context; project Contexts;
  • poll, a poll within the Context; project Contexts;
  • post, a comment for a parent Post object; Context type independent.

Post.topic

Only post type Post objects belong to a parent Post which guid should be specified in the topic property. The system design assumes only a two-level Posts hierarchy.

Post.resolution

Post types issue and poll topics might have a resolution to expose the current status. The only way to change topic resolution is creating a dependent post with resolution property set.

Resolutions for issue Post objects:

  • unconfirmed, newly created issue;
  • new, confirmed issue;
  • needinfo, posted information about the issue is insufficient, more details needed;
  • resolved, the issue is resolved, closed;
  • unrelated, the issue does not related to the Context, closed;
  • obsolete, the issue is already solved in recent Context releases, closed;
  • duplicate, the issue is a duplicate, closed.

Resolutions for poll Post objects:

  • open, the poll is open for votes;
  • closed, the poll is closed for votes.

Base API

List of actions common of all API providers. 

POST /RESOURCE

Create new resource object.

JSON object keys to send:

  • RESOURCE's properties.

JSON object keys to receive:

  • guid, with globally unique identifier that specifies the created object.
PUT /RESOURCE/GUID

Modify resource object. By default, might be called only by GUID creator.

JSON object keys to send:

  • RESOURCE's properties to modify.
DELETE /RESOURCE/GUID

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 GUID creator. 

GET /RESOURCE[?offset=INTEGER][&limit=INTEGER][&query=STRING][&reply=PROP][&order_by=[+|-]PROP][&group_by=PROP][&PROP=VALUE][&!PROP=VALUE]

Find resource objects.

Where:

  • offset, int
    start index to return entries from, the default value is 0;
  • limit, int
    do not return more then specified value, maximal and default values are being setup on server side;
  • query, str
    search request in Xapian notation; if property is boolean, integer or datetime, it supports searching by ranges, i.e., PROP:[START]..[END];
  • PROP, str
    supplements query with filtering by exact value of the PROP property; the resulting query string will be PROP=VALUE AND (QUERY); argument is multiple;
  • !PROP, str
    supplements query by excluding exact value of the PROP property; the resulting query string will be NOT PROP=VALUE AND (QUERY); argument is multiple;
  • reply, str
    RESOURCE properties to return; by default, return only guid property; argument is multiple;
  • order_by, str
    property to sort the resulting list by; if starts with the -, the order is descending, otherwise it is ascending;
  • group_by, str
    property name to group resulting list by.

JSON object keys to receive:

  • total, total number in requested query (the reply might contain only the portion restricted by limit request argument);
  • result, an array of dictionaries with resource object properties, dictionaries contain at least guid property.
GET /RESOURCE/GUID[?reply=PROP]

Where:

  • reply, str
    RESOURCE properties to return; by default, return only guid property; argument is multiple;

Return properties for a particular resource object.

JSON object keys to receive:

  • properties that were specified in reply argument(s), at least guid.
PUT /RESOURCE/GUID/PROP

Modify particular resource property. By default, might be called only by GUID creator. 

GET /RESOURCE/GUID/PROP

Return property value for particular resource object.

Data to receive:

  • property value in JSON notation for regular properties;
  • raw data or redirection for BLOB properties.

Aggregated properties

Aggregated properties have special API to treat their content. 

POST /RESOURCE/GUID/PROP

Submit new item. The command returns an id for newly created aggregated item. Depending on particular property, new items might be created not only by object's authors. 

PUT /RESOURCE/GUID/PROP/ID

Update existing aggregated item. Depending on particular property, the command is allowed either to object's authors or to aggregated item submitter. 

DELETE /RESOURCE/GUID/PROP/ID

Delete existing aggregated item. Depending on particular property, the command is allowed either to object's authors or to aggregated item submitter.

Notifications

It is possible to subscribe to server events. Notification will happen using HTML5 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:

  • event
    event type.

Node API

This is an API provided by Sugar Network nodes on top of base one.

Authentication

Right now, the only way to be authenticated on a Sugar Network server is by running a local application on the client side and using the API it 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 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 releases and avoid reading raw Context.releases property, there are special high-level API commands. 

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.

Solving requirements might be:

  • LSB_ID, if Context releases depend on system packages, specify the LSB distributor id to consider while choosing particular packages;
  • LSB_RELEASE, if Context releases depend on system packages, specify the LSB release number of the distribution to consider while choosing particular packages;
  • DEPENDENCY-VERSION, the assume argument instructs server to assume that specified 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 sugar-0.94 because neither lsb_id nor 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:

  • blob, bundle digest to download;
  • version, chosen version number;
  • title, the Context.title value;
  • command, a command to launch the bundle, only for Sugar activities.

For example, the GET /context/org.laptop.TurtleArtActivity?cmd=solve&assume=sugar-0.94 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 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

To easy upload Context releases and avoid writing to raw Context.releases property, there is a special high-level API command. 

POST /context?cmd=submit[&PROP=VALUE][&initial]

Where the PROP arguments are optional release properties. The initial argument asks the system to create new Context resource new release will belong to.

The posting data might be two types,

  • Sugar activities in .xo bundles,
    there is no need in PROP arguments, all properties will be populated basing on metadata from a .xo bundle; including release notes from the CHANGELOG file in Markdown notation; besides, only in this case initial makes sense because it is the only way to get Context properties;
  • Arbitrary data,
    all required release properties should be specified in PROP arguments, at least context and version; license should be specified only if there are no existing releases to pickup license from.

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][&event=EVENT][&limit=NUMBER]

Where:

  • start and end is a time interval to get statistics for; if omitted, the beginning and the end of entire life cycle will be used;
  • event, multiple argument to specify what stats should be returned; if omitted, return all sources;
  • limit, number of stat records to return for the start-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 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 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

The reasons to proxy Sugar Network data on users side:

Proxying happens by providing the same Sugar Network API (with some extra functionality, see below) from local process launched beforehand.

Offline mode

Being connected to a Sugar Network node, local proxy provides 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. 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:

  • Favorited Contexts
    to select preferred Context resources; these Contexts will be marked by favorite value in the Context.layer property;
  • Checked-in Contexts
    to keep most recent Context (for activity and book types) version in local storage to make it available in offline; note that there is no need in checking-in to speedup online lunch, versions are being cached anyway; these Contexts will be marked by checkin value in the Context.layer property.

To control users preferences there are special API commands: 

PUT /context/GUID?cmd=favorite

Set favorite status. 

DELETE /context/GUID?cmd=favorite

Unset favorite status. 

PUT /context/GUID?cmd=checkin[&spawn]

Check-in the specified Context. By default, the command will return streamed text/event-stream MIME type data to monitor the progress. If the spawn argument is specified, the command will exit immediately with asynchronous sending progress events. 

DELETE /context/GUID?cmd=checkin

Checkout the Context.

Launching

Sugar Network Contexts (for activity and book types) can be launched as-is. The launching process is implicit and includes selecting the most recent (and appropriate for software contexts) version, downloading bundles from the Sugar Network, installing missed software dependencies, execution itself. All downloaded bundles will be cached [with further garbage collecting] to speedup further launching.

Sugar activities will be directly executed. Book Contexts will be opened in the proper application according to its MIME type. 

GET /context/GUID?cmd=launch[&args=ARG][&activity_id=ACTIVITY_ID][&object_id=OBJECT_ID][&uri=URI][&app=APP][&spawn]

Arguments that make sense only for Sugar activities:

  • ARG, command line argument to pass to launched activities, repeat ARG for each argument;
  • ACTIVITY_ID, internal activity id which will be auto set if omitted;
  • OBJECT_ID, Journal object id to resume;
  • URI, URL to resume if activity supports this functionality.

Arguments that make sense only for books:

  • APP, specify application Context to open the book by; if omitted, the system will try to find most appropriate option, among all existing software Contexts.

Common arguments:

  • 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 spawn argument is specified, the command will exit immediately with asynchronous sending launching events.

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. This kind of access might be useful when local applications cannot use DBus sugar-datastore API, e.g., Javascript applications. API to Journal is restricted only to read-only access: 

GET /journal?offset=INTEGER&limit=INTEGER[&query=STRING][&order_by=[+|-]PROP][&QUERY_PROP=VALUE[&...]]
GET /journal/JOURNAL_ID[?reply=PROP[,..]]
GET /journal/JOURNAL_ID/PROPERTY

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, sugar-network, which takes care about Sugar Network specific like launching local API (if it is not already available) to get access to local proxy.

The sugar-network command-line format is below. Call sugar-network --help for more detailed info. 

sugar-network GET|POST|PUT|DELETE PATH ARG=VALUE [..]
  • PATH, is an url path;
  • ARG=VALUE, request arguments as they being passed to in url.

POST and PUT commands require data to pass, use the following command-line arguments:

  • -f FILE to specify the file to pass;
  • -d DATA to specify string to pass;
  • -j posted data should be encoded into JSON before posting.

Getting involved

  • Submit your bug report or feature request.
  • Browse our implementation discussions, and post your feedback. (You should join this discussion list in order to avoid having your messages postponed for moderation.)
Retrieved from "https://wiki.sugarlabs.org/index.php?title=Sugar_Network/API&oldid=93401"