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 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. There are common events that all resources might generate.

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, e.g., http://api-testing.network.sugarlabs.org;
• 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 particular action.

If request needs to send data, it should send Python dictionary converted to JSON notation.

In most cases (see actions for exceptions), 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. Otherwise, dictionary keys in response will be set accordingly to the particular request.

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.

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 searching PROP for exact VALUE; it is different to regular <PROP>:<VALUE> where VALUE might be a substring of exact PROP value;
• QUERY_PROP, str
  supplement query with filtering by property value, the resulting query string will be QUERY_PROP=VALUE AND (query);
• reply, str
  coma separated list of RESOURCE properties to return; by default, return only guid 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 by limit request argument);
• result, an array of dictionaries with resource object properties, dictionaries contain at least guid 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 least guid.

GET /<RESOURCE>/<GUID>/<PROPERTY>[?reply=<PROP>[,..]]

Return property value for particular resource object.

Data to receive:

• property value in JSON notation.

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