Sugar Network/API

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.

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. Resources might support common actions. While processing requests, the server might generate events.

The API is RESTful, and is 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, 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 servers

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);

• node-testing.sugarlabs.org
  Recent stable release with regular data import from the production server; is still free for any experiments;

• node.sugarlabs.org
  Production server;

• localhost:5001
  default url to get access to local proxy provided from user side application.

Sugar Network 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.

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

Common actions

List of actions common of all resources.

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 with the following additions:
  • if property is boolean, integer or datetime, it supports searching by ranges: PROP:[START]..[END];
  • the statement PROP:=["]VALUE["] has the same effect as QUERY_PROP; it is different to regular PROP:VALUE where VALUE might be a substring;
• 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.

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.

HEAD /RESOURCE/GUID/PROP

Return property metadata for particular resource object. In addition to regular HTTP header properties, the command will return Sugar Network property metadata in header keys prefixed by X-SN-.

Download activities

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[&requires=DEPENDENCY][&PROP=VALUE]
HEAD /context/GUID?cmd=clone[&requires=DEPENDENCY][&PROP=VALUE]

Using passed parameters, this command finds out proper Implementation and returns its bundle. If there are more than one implementation, the most recent version will be chosen.

Command parameters might be any Implementation property values, such as stability or version, to filter implementations by. The requires parameter has a special meaning, it is intended to select an implementation by its dependency list. DEPENDENCY value is multiple and should conform Sugar Network recipe specification.

The HEAD command will not return bundle itself but rather its metadata combined with selected Implementation properties.

Upload new releases

The regular procedure to upload new Implementation objects is using the POST /implementation API command with specifying new Implementation properties and PUT'ing new bundle itself. To make this process shorter, there is a special API command.

POST /implementation?cmd=release[&PROP=VALUE][&initial]

Where the PROP arguments are optional Implementation properties to create new resource. The initial argument asks the system to create new Context resource new Implementation 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 Implementation properties should be specified in PROP arguments, at least context and version; license should be specified only if there are no existing Implementations to pickup license from.

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 statistics

While working, Sugar Network servers collect depersonalized and common statistics. To read such info, call the command:

GET /?cmd=stats&start=SECONDS&end=SECONDS&records=NUMBER&source=STATS-NAME

Where:

• start and end is a time interval to get statistics for;
• records, 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, 366 days;
• source, multiple argument to specify what stats should be returned.

Client proxy

The reasons to proxy Sugar Network data on users side:

• Seamless support offline workflow;
• 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 local process launched beforehand.

Offline case

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.

Besides, local Sugar Network storage will be reused to keep users preferences, such as:

• favorite contexts
  to select preferred Context resources; these contexts will be marked by favorite value in the Context.layer property;

• cloned contexts
  to keep most recent context Implementation in local storage to make it available in offline; note that there is no need in cloning to speedup online lunch, Implementations are being cached anyway; these contexts will be marked by clone value in the Context.layer property.

To control users preferences there are special API commands:

PUT /context/GUID?cmd=favorite

Change favorite status. PUT content should be favorite status.

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

Change cloning status for the specified context. PUT content should be cloning status. By default, the command will return streamed text/event-stream MIME type data to monitor the whole cloning process. If the spawn argument is specified, the command will exit immediately with asynchronous sending cloning events.

Launching

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

Sugar activities (with activity value in the Context.type property) will be directly executed. Non-software contexts will be opened in the proper application according to its Implementation.mime_type.

GET /context/GUID?cmd=launch[&args=ARG][&activity_id=ACTIVITY_ID][&object_id=OBJECT_ID][&uri=URI][&context=CONTEXT][&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 non-software contexts:

• CONTEXT, specify application Context to open the launching implementation by; if omitted, the system will try to find most appropriate option, among all existing software contexts, using Context.mime_types property.

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.

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.)