Difference between revisions of "Sugar Network/API"

From Sugar Labs
Jump to navigation Jump to search
(Actualize API, s/player/user/g)
Line 46: Line 46:
 
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.
 
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=<>[&request=<PROP>:<VALUE>[,...]][&query=<>][&properties=<PROP>[,..]][&order_by=<nowiki>[+|-]</nowiki><PROP>]
+
  GET /<RESOURCE>?offset=<INTEGER>&limit=<INTEGER>[&query=<STRING>][&reply=<PROP>[,..]][&order_by=<nowiki>[+|-]</nowiki><PROP>][&<QUERY_PROP>=<VALUE>[&...]]
  
 
Find ''RESOURCE'' objects.
 
Find ''RESOURCE'' objects.
Line 53: Line 53:
 
:* {{Code|offset}}, ''int''<br>start index to return entries from;
 
:* {{Code|offset}}, ''int''<br>start index to return entries from;
 
:* {{Code|limit}}, ''int''<br>do not return more then specified value;
 
:* {{Code|limit}}, ''int''<br>do not return more then specified value;
−
:* {{Code|request}}, ''dict''<br>search request in key-value pairs;
 
 
:* {{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 with the following additions:
 
:** if property is boolean, integer or datetime, it supports searching by ranges: {{Code|<PROP>:[<START>]..[<END>]}};
 
:** if property is boolean, integer or datetime, it supports searching by ranges: {{Code|<PROP>:[<START>]..[<END>]}};
 
:** 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;
 
:** 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|properties}}, ''str''<br>coma separated list of ''RESOURCE'' properties to return; by default, return only {{Code|guid}} property;
+
:* {{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>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.
  
Line 66: Line 66:
 
:* An array of dictionaries with ''RESOURCE'' properties, dictionaries contain at least {{Code|guid}} property.
 
:* An array of dictionaries with ''RESOURCE'' properties, dictionaries contain at least {{Code|guid}} property.
  
−
  GET /<RESOURCE>/<GUID>[?properties=<PROP>[,..]]
+
  GET /<RESOURCE>/<GUID>
  
 
Return ''RESOURCE'' properties the of particular object.
 
Return ''RESOURCE'' properties the of particular object.
−
 
−
Where:
 
−
:* {{Code|properties}}, ''str''<br>coma separated list of ''RESOURCE'' properties to return; by default, return all properties.
 
  
 
Receives:
 
Receives:

Revision as of 22:16, 8 March 2012

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|ACTION>[/<ACTION>]][?<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.

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=<INTEGER>&limit=<INTEGER>[&query=<STRING>][&reply=<PROP>[,..]][&order_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.

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>

Return RESOURCE properties the of particular object.

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

Resources

user

Actions:

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

Send private message to the user.

Sends:

A dictionary with event properties.

Events:

Direct event to the user:
  • type: message.

context

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 /context/<GUID/add_member?member=<USER>

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

Events:

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

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

Events:

  • type: remove_member;
  • memeber: GUID.

question

Actions:

idea

Actions:

problem

Actions:

review

Actions:

wiki

Actions:

gallery

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

version

Actions:

report

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.

Actions:

comment

event

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=76357"