Sugar Labs

Sugar Network/API

< Sugar Network
Revision as of 08:20, 2 January 2012 by Alsroot (talk | contribs) (→‎Objects model)

This page describes the APi that Sugar Network clients use to interact with Sugar Network server. See also technical introduction page.

Overview

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|ACTION>[/<ACTION>]]?<AUTH-TOKEN>=<>[&<ARG>=<>]..]

When:

  • RESOURCE value is one of existing resources;
  • GUID, the RESOURCE's particular object;
  • ACTION and a set of ARGs depend on particular RESOURCE.

Besides, particular request can send and receive data in JSON notation. If request processing was failed, the reply is a JSON directory that contains error key with error message.

For the beginning, API is not secure for reasons:

  • Implement initial version in short period of time;
  • The only users, for the beginning, are teachers and students from one-teacher off-line schools.

In particular:

  • API is being provided only via HTTP;
  • The AUTH-TOKEN is the uid which is a hashed value from Sugar profile public SSH key (the same as JID value in Sugar Shell but without the domain part) that does not require any handshake procedures.

Objects model

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.

Commons

Actions

Actions might be restricted for particular resource, see the corresponding section for detailed information. 

POST /<RESOURCE>

Create new RESOURCE object.

Sends:

Resource properties.

Receives:

  • guid, str
    globally unique identifier that specifies created object;
PUT /<RESOURCE>/<GUID>

Modify the specified RESOURCE object. By default, might be called only by RESOURCE creator.

Sends:

Keys that need to be modified.
DELETE /<RESOURCE>/<GUID>

Delete the specified 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 RESOURCE creator. 

GET /<RESOURCE>?offset=<>&limit=<>[&query=<>][&properties=<PROP>[,..]][&order_by=[+|-]<PROP>[,..]][&group_by=<PROP>]

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;
  • properties, str
    coma separated list of RESOURCE properties to return; by default, return only guid property;
  • order_by, str
    coma separated list of RESOURCE properties to sort the resulting list; if an property starts with the -, the order is descending, otherwise it is ascending;
  • group_by, str
    a property name to group resulting list by; if was specified, every resulting list item will contain grouped key with a number of entries that are represented by the current one.

Sends:

  • A dictionary with RESOURCE's properties to restrict the resulting list.

Receives:

  • An array of dictionaries with RESOURCE properties, dictionaries contain at least guid property.
GET /<RESOURCE>/<GUID>[?properties=<PROP>[,..]]

Return RESOURCE properties the of particular object.

Where:

  • properties, str
    coma separated list of RESOURCE properties to return; by default, return all properties.

Receives:

  • A dictionary with RESOURCE properties that contains at least guid property.

Wiki actions

Some of resources have Wiki pages associated. The following actions can be used to manage these Wiki pages. 

GET /<RESOURCE>/<GUID>/wikitext

Get the Wiki sources.

Receives:

Wiki sources with text/plain MIME type.
GET /<RESOURCE>/<GUID>/rendered_wikitext

Get the Wiki rendered to HTML.

Receives:

Rendered Wiki with text/html MIME type.
PUT /<RESOURCE>/<GUID>/wikitext

Put new content for Wiki page. Only object creator can use it.

Sends:

Wiki sources with text/plain MIME type.

Events:

type: update

Events

All events have the following common properties:

  • type, str
    the type of event;
  • timestamp, int
    the UNIX seconds in UTC timezone of the time when event was created;
  • resource, str
    the name of affected resource;
  • object, guid
    the GUID of affected resource object;
  • creator
    the GUID of a player the event was created on behalf of.

Different types of events might add new options.

There are the following common event types:

The particular resource was created:
  • type: create
The particular resource properties were modified:
  • type: update
The particular resource was deleted (hidden):
  • type: delete

Resources

player

Properties:

  • nickname, str, read
    set by Sugar Shell;
  • color, str, read
    colors pair in format #RRGGBB,#RRGGBB, set by Sugar Shell.

Calculated properties:

  • reputation, int, read
    current player's reputation based on:
    • direct votes from other players,
    • votes given to objects where the player is a creator;
  • vote, bool, read, write
    did url requester voted for the current object or not;

Actions:

  • player cannot be created or destroyed;
  • player can be updated only by a user who is associated with it.
POST /player/<GUID>/message

Send private message to the player.

Sends:

A dictionary with event properties.

Events:

Direct event to the player:
  • type: message.

project

Properties:

  • title, str, read, write only for the team members
    one line title;

description;

  • type, str, read, write only for the team members
    the project type:
    • general,
    • activity,
    • wiki,
    • gallery;
  • zoom, str, read, write only for the team members
    Network Zoom level that project belongs:
    • worldwide,
    • neighbourhood,
    • private.

Calculated properties:

  • reputation, int, read
    current project's reputation based on:
    • direct votes from other players,
    • votes given to related objects if theirs respect property is empty;
  • vote, bool, read, write
    did url requester voted for the current object or not.

Actions:

  • right after creation, the creator will be the only team member;
  • update and delete actions are allowed only for team members;
  • Wiki related actions to manage object description.
POST /project/<GUID/add_member?member=<PLAYER>

Make a PLAYER the team member. Only team members can call this action.

Events:

  • type: add_member;
  • memeber: GUID.
POST /project/GUID/remove_member?member=<PLAYER>

Remove PLAYER from the to the team. Only team member can call this action if he is not the PLAYER and PLAYER is not the same as creator.

Events:

  • type: remove_member;
  • memeber: GUID.

question

Properties:

  • project, guid, read
    the project this object belongs to;
  • title, str, read, write only for creator
    one line title;
  • solution, guid, read, write only by creator
    the solution which solves the object.

Calculated properties:

  • implementation_status, str, read
    if question has an associated objective, this objective's status is a status of the question, otherwise the property is empty.

Actions:

idea

Properties:

  • project, guid, read
    the project this object belongs to;
  • title, str, read, write only for creator
    one line title.

Calculated properties:

  • implementation_status, str, read
    if idea has an associated objective, this objective's status is a status of the idea, otherwise the property is empty.

Actions:

problem

Properties:

  • project, guid, read
    the project this object belongs to;
  • title, str, read, write only for creator
    one line title;
  • solution, guid, read, write only by creator
    the solution which solves the object.

Calculated properties:

  • implementation_status, str, read
    if problem has an associated objective, this objective's status is a status of the problem, otherwise the property is empty.

Actions:

wiki

Properties:

  • project, guid, read
    the project this object belongs to;
  • title, str, read, write only for creator
    one line title.

Actions:

gallery

Properties:

  • project, guid, read
    the project this object belongs to;
  • title, str, read, write only for creator
    one line title.

Actions: 

GET /gallery/<GUID>/exhibit

Get the attached object.

Receives:

Attached object content with application/octet-stream MIME type.
PUT /gallery/<GUID>/exhibit

Put new attached object. Only object creator can use it.

Sends:

Attached object content with application/octet-stream MIME type.

Events:

type: update

objective

Properties:

  • project, guid, read
    the project this object belongs to;
  • title, str, read, write only for the team members
    one line title.

Actions:

release

Properties:

  • project, guid, read
    the project this object belongs to;
  • version, str, read
    release version;
  • stability, str, read
    release stability level, the same as for Zero Install/Sweets.

Actions:

report

Properties:

  • release, guid, read
    the release this object belongs to.

Actions:

Only read-only common actions.
PUT /report/<GUID>/logs

Attach logs to the report.

Sends:

Attached logs with application/octet-stream MIME type.

Events:

type: update
GET /report/<GUID>/logs

Get report attached logs.

Receives:

Attached logs with application/octet-stream MIME type.

solution

The solution for question/idea/problem objects.

Properties:

  • resource, str, read
    the type of resource this solution is for;
  • object, guid, read
    the resource object this solution is for.

Actions:

comment

Properties:

  • resource, str, read
    the type of resource this comment is about;
  • object, guid, read
    the resource object this comment is about;
  • text, str, read, write only for creator
    comment text.

event

Properties:

No specific properties except the common ones.

Actions:

Only read-only common actions.

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

Changelog

This section shows how API is evolving. The API state is being described by a version. The major number is being changed only if backwards compatibility was broken.

1.0

Not yet released API.
Retrieved from "https://wiki.sugarlabs.org/index.php?title=Sugar_Network/API&oldid=73860"