Sugar Network/API
This page describes the API that Sugar Network clients use to interact with Sugar Network server. See also a guide to basic Sugar Network concepts and its twin page from technical point of view. Besides, visit the introduction page.
Overview
To better understand this API, see technical explanation of the conceptual level and objects model in particular.
The API operates with Sugar Network resources that are collections of objects. All objects are identified by global unique identifiers, GUIDs. Resources might support common actions. While processing requests, server might generate events. Besides, API provides extra resources that are not Sugar Network objects.
The API is RESTful and being served via HTTP(S) using JSON notation. The common RESTful 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
, theRESOURCE
's particular object;PROPERTY
, particular property ofGUID
object;COMMAND
, optional command name; combination of HTTP request method (GET
,POST
,PUT
, or,DELETE
) and [possibly empty]COMMAND
composes the requested action;ARGUMENT
s andVALUE
s depend on particular action.
If request needs to send data, it should send Python dictionary converted to JSON notation.
In most cases, server replies with dictionary in JSON notation. If request was failed, the replied dictionary will contain request
, with original request, and error
, with error message, keys. In the rest of cases, response might be variable.
API servers
These are standard Sugar Network API servers publicly available.
- api-devel.network.sugarlabs.org
Development server that is being updated to keep it synchronized with this document; it does not contain important data and free for any experiments;
- api-testing.network.sugarlabs.org
Recent stable release with data that is being used in pilots; do not create temporal content here, use devel server instead;
- localhost:5001
default url to get access to local data served from local application.
Sugar Network resources
The following diagram shows the full list of objects implemented by the Sugar Network API.
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.
Authentication
Right now, the only way to be authenticated on a Sugar Network server is running sugar-network-service
on client side and use API it provides.
TODO
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.
TODO
Common actions
List of actions common of all resources.
POST /<RESOURCE>
Create new resource object.
Dictionary to send:
RESOURCE
's properties.
Dictionary keys to receive:
guid
, with globally unique identifier that specifies created object.
PUT /<RESOURCE>/<GUID>
Modify resource object. By default, might be called only by GUID
creator.
Dictionary to send:
RESOURCE
's properties to modify.
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 GUID
creator.
GET /<RESOURCE>?offset=<INTEGER>&limit=<INTEGER>[&query=<STRING>][&reply=<PROP>[,..]][&order_by=[+|-]<PROP>][&group_by=<PROP>][&<QUERY_PROP>=<VALUE>[&...]]
Find resource objects.
Where:
offset
, int
start index to return entries from;limit
, int
do not return more then specified value;query
, str
search request in Xapian notation with the following additions:- if property is boolean, integer or datetime, it supports searching by ranges:
<PROP>:[<START>]..[<END>]
; - the statement
<PROP>:=["]<VALUE>["]
means(<THE-REST_QUERY>) AND <EXACT-PROP-SEARCH>
with searchingPROP
for exactVALUE
; it is different to regular<PROP>:<VALUE>
whereVALUE
might be a substring of exactPROP
value;
- if property is boolean, integer or datetime, it supports searching by ranges:
QUERY_PROP
, str
supplementquery
with filtering by property value, the resulting query string will beQUERY_PROP=VALUE AND (query)
;reply
, str
coma separated list of RESOURCE properties to return; by default, return onlyguid
property;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.
Dictionary keys to receive:
total
, total number in requested query (the reply might contain only portion restricted bylimit
request argument);result
, an array of dictionaries with resource object properties, dictionaries contain at leastguid
property.
GET /<RESOURCE>/<GUID>[?reply=<PROP>[,..]]
Return properties for particular resource object.
Dictionary keys to receive:
- properties that were specified in
reply
argument(s), at leastguid
.
- properties that were specified in
GET /<RESOURCE>/<GUID>/<PROPERTY>
Return property value for particular resource object.
Data to receive:
- property value in JSON notation.
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[&only_commits=1]
Where:
only_commits
,
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:
event
event type.
Usage statistics
In order to collect usage statistics gathered in local users' environment by sugar-client, API provides related commands for User Sugar Network resource.
GET /user/GUID?cmd=stats-info
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.
POST /user/GUID?cmd=stats-upload
Upload statistics. Request content should be in JSON notation and be a dictionary of:
name
name of RRD database to upload stats to;values
an array oftimestamp, row
tuples whenrow
is a dictionary of database field names and values.
GNU/Linux packages metadata
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.
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.
Packages project might be considered as a temporal solution when, and if, AppStream's MetadataNotes will be reused in the future.
Additional resources
In addition to direct Sugar Network resources, API provides related content.
packagekit-backend-presolve
In order to provide GNU/Linux-distribution-agnostic launches of activities, Sugar Network API supports packagekit-backend-presolve users.
API server provides the following kinds of urls:
GET /packages
list all supported platforms;GET /packages/<PLATFORM>
list all supported packages for a particular platform;GET /packages/<PLATFORM>/<PACKAGE>
pre-solved dependency graph for a particular package.
Where:
PLATFORM
one of supported packagekit-backend-presolve platforms, e.g., OLPC-13.0.1;PACKAGE
a name of the particular package.
Using Packages' metadata, Sugar Network will automatically generate dependency graphs for packagekit-backend-presolve.
Local access
If 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. The reasons to provide API from local host:
- Provide assess to local Sugar Network data;
- Transparent treating of offline accessible Sugar activities;
- Be a unified (with network server API) IPC method for local applications.
Mountpoints
To differentiate what particular Sugar Network source is needed, requests might have mountpoint
argument which can be one of the following values:
/
, 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;
~
, Sugar Network content located in~/.sugar/PROFILE/network
directory; this mountpoint might support special use cases, see the rest of this text;
PATH
, absolute path in local files system to a directory with Sugar Network content, e.g., it might be content on mounted disk,/media/DISK
.
The mountpoint /
, in addition to proxing user requests to a Sugar Network server, provides the following functionality:
- user is already authenticated, e.g., it is possible to change content on Sugar Network server.
There are the following mountpoints related commands:
GET /?cmd=mounts
Returns a list of all accessible mountpoints. List items are dictionaries with the following keys:
mountpoint
, mountpoint;name
, i18n name of the mountpoint;private
, boolean flag;True
if the mountpoint is accessible only from localhost.
Offline activities
To get access to /
mountpoint activities even if there is no server connection, activities need to be accessible from ~
mountpoint. There are special Context properties, on all mountpoints, that control what activities exist on ~
mountpoint:
keep
Bookmarked context which metadata is accessible from~
mountpoint;keep_impl
Most recent version of the corresponding Context is accessible from~
mountpoint being placed to~/Activities
directory.
Both properties are writable, so, it is possible to set keep_impl
property to True
for a Context on /
mountpoint to make sure that after going offline, this Context will remain runnable. The same true for clearing keep_impl
as well.
Launch activities
All activities, not only from ~
mountpoint, can be launched as-is.
GET /context/GUID?cmd=launch[&args=ARG][&activity_id=ACTIVITY_ID][&context=CONTEXT][&object_id=OBJECT_ID][&uri=URI][&color=COLOR][&no_spawn=NO_SPAWN]
ARG
, command line argument to pass to launched activities, repeatARG
for each argument;ACTIVITY_ID
, internal activity id which will be auto set if omitted;OBJECT_ID
, id to resume Journal object; it might be GUID of a Sugar Network resource as well;CONTEXT
, Sugar Network Context to resume, see Resume activities for details;URI
, URL to resume if activity supports this functionality;COLOR
, coma separated pair of Sugar colors to assign to activity object;NO_SPAWN
, if specified, HTTP connection will not be closed until exiting activity process.
~
mountpoint activities will be launched as-is from ~/Activities
directory. For /
mountpoint, activities will be downloaded from the server and kept in cache directory. It is possible that during preparing for launching will be installed activity dependencies.
Resume activities
While launching it is possible to open various objects. There are several use-cases:
- Resume local Journal object
OBJECT_ID
launch parameter is set to Journal id andCONTEXT
is not set;
- Resume Sugar Network Artifact resources
OBJECT_ID
launch parameter is set to proper Artifact GUID andCONTEXT
to Context GUID the artifact belongs to;
- Resume Sugar Network Context resources
OBJECT_ID
is not set andCONTEXT
is set to Context GUID to find most recent Implementation to resume.
For the last two cases, particular objects will be downloaded and placed to the Journal (with keeping GUIDs as Journal IDs) to make it possible to open from from launched activity.
Access to the Journal
It is possible to get access to local Sugar Journal using special, journal, resource. 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
This kind of access might be useful when local applications cannot use DBus sugar-datastore API, e.g., Javascript applications.
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.)