Sugar Labs

Sugar Network/API: Difference between revisions

← Older editNewer edit →
No edit summary
Line 9: Line 9:
The API is [[Wikipedia:Restful|RESTful]] and being served via HTTP(S) using [[Wikipedia:Json|JSON]] notation. The common RESTful request url format is:
The API is [[Wikipedia:Restful|RESTful]] and being served via HTTP(S) using [[Wikipedia:Json|JSON]] notation. The common RESTful request url format is:


  http[s]://<SERVER>/<RESOURCE>[/<GUID|ACTION>[/<ACTION>]][?<ARG>=<>..]
  http[s]://<SERVER>[/<RESOURCE>[/<GUID>[/<PROPERTY>]]][?[cmd=<COMMAND>][&<ARGUMENT>=<VALUE>..]]


When:
When:


* ''RESOURCE'' value is one of [[#Resources|existing]] resources;
* {{Code|SERVER}}, particular Sugar Network API server, e.g., http://api-testing.network.sugarlabs.org;
* ''GUID'', the ''RESOURCE'''s particular object;
* {{Code|RESOURCE}}, name one of the [[#Resources|existing]] resources;
* ''ACTION'' and a set of ''ARG''s depend on particular ''RESOURCE''.
* {{Code|GUID}}, the {{Code|RESOURCE}}'s particular object;
* {{Code|PROPERTY}}, particular property of {{Code|GUID}} object;
* {{Code|COMMAND}}, optional command name; combination of HTTP request method ({{Code|GET}}, {{Code|POST}}, {{Code|PUT}}, or, {{Code|DELETE}}) and [possibly empty] {{Code|COMMAND}} composes the requested [[#Actions|action]];
* {{Code|ARGUMENT}}s and {{Code|VALUE}}s depend on particular [[#Actions|action]].


If request needs to send data, it should send Python dictionary converted to [[Wikipedia:Json|JSON]] notation.
If request needs to send data, it should send Python dictionary converted to [[Wikipedia:Json|JSON]] notation.


Server all time replies with dictionary in JSON notation. If request was failed, the replied dictionary will contain {{Code|request}}, with original request, and {{Code|error}}, with error message, keys. Otherwise, dictionary keys in response will be set accordingly to the particular request.
In most cases (see [[#Actions|actions]] for exceptions), server replies with dictionary in JSON notation. If request was failed, the replied dictionary will contain {{Code|request}}, with original request, and {{Code|error}}, with error message, keys. Otherwise, dictionary keys in response will be set accordingly to the particular request.


== Commons ==
== Resources ==


=== Actions ===
{{:Platform_Team/Sugar_Network/Objects_model}}


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


POST /<RESOURCE>
List of actions common of all resources.


Create new ''RESOURCE'' object.


Dictionary keys to send:
'''POST''' /<RESOURCE>
: ''RESOURCE'' properties.
 
Create new resource object.
 
Dictionary to send:
: {{Code|''RESOURCE}}'s properties.


Dictionary keys to receive:
Dictionary keys to receive:
:* {{Code|guid}}, with globally unique identifier that specifies created object.
:* {{Code|guid}}, with globally unique identifier that specifies created object.


PUT /<RESOURCE>/<GUID>


Modify the specified ''RESOURCE'' object. By default, might be called only by ''RESOURCE'' creator.
'''PUT''' /<RESOURCE>/<GUID>
 
Modify resource object. By default, might be called only by {{Code|GUID}} creator.
 
Dictionary to send:
: {{Code|RESOURCE}}'s properties to modify.
 


Dictionary keys to send:
'''DELETE''' /<RESOURCE>/<GUID>
: ''RESOURCE'' 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 {{Code|GUID}} 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=<INTEGER>&limit=<INTEGER>[&query=<STRING>][&reply=<PROP>[,..]][&order_by=<nowiki>[+|-]</nowiki><PROP>][&<QUERY_PROP>=<VALUE>[&...]]
  '''GET''' /<RESOURCE>?offset=<INTEGER>&limit=<INTEGER>[&query=<STRING>][&reply=<PROP>[,..]][&order_by=<nowiki>[+|-]</nowiki><PROP>][&group_by=<PROP>][&<QUERY_PROP>=<VALUE>[&...]]


Find ''RESOURCE'' objects.
Find resource objects.


Where:
Where:
Line 60: Line 69:
:* {{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|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|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;
:* {{Code|group_by}}, ''str''<br>property name to group resulting list by.


Dictionary keys to receive:
Dictionary keys to receive:
:* {{Code|total}}, total number in requested query (the reply might contain only portion restricted by {{Code|limit}} request argument);
:* {{Code|total}}, total number in requested query (the reply might contain only portion restricted by {{Code|limit}} request argument);
:* {{Code|result}}, an array of dictionaries with ''RESOURCE'' properties, dictionaries contain at least {{Code|guid}} property.
:* {{Code|result}}, an array of dictionaries with resource object properties, dictionaries contain at least {{Code|guid}} property.


GET /<RESOURCE>/<GUID>


Return ''RESOURCE'' properties the of particular object.
'''GET''' /<RESOURCE>/<GUID>[?reply=<PROP>[,..]]
 
Return properties for particular resource object.


Dictionary keys to receive:
Dictionary keys to receive:
:* ''RESOURCE'' properties that contains at least {{Code|guid}} property.
:* properties that were specified in {{Code|reply}} argument(s), at least {{Code|guid}}.


=== Wiki actions ===


Some of resources have Wiki pages associated. The following actions can be used to manage these Wiki pages.
'''GET''' /<RESOURCE>/<GUID>/<PROPERTY>[?reply=<PROP>[,..]]


GET /<RESOURCE>/<GUID>/'''wikitext'''
Return property value for particular resource object.


Get the Wiki sources.
Data to receive:
 
:* property value in JSON notation.
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:
: {{Code|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|event]] properties.
 
Events:
: Direct event to the ''user'':
:* {{Code|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_actions|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:
:* {{Code|type: add_member}};
:* {{Code|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:
:* {{Code|type: remove_member}};
:* {{Code|memeber: GUID}}.
 
=== question ===
 
Actions:
* [[#Wiki_actions|Wiki related actions]] to manage object description.
 
=== idea ===
 
Actions:
* [[#Wiki_actions|Wiki related actions]] to manage object description.
 
=== problem ===
 
Actions:
* [[#Wiki_actions|Wiki related actions]] to manage object description.
 
=== review ===
 
Actions:
* [[#Wiki_actions|Wiki related actions]] to manage object description.
 
=== wiki ===
 
Actions:
* [[#Wiki_actions|Wiki related actions]] to manage Wiki page.
 
=== gallery ===
 
Actions:
* [[#Wiki_actions|Wiki related actions]] to manage object description.
 
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:
: {{Code|type: update}}
 
=== version ===
 
Actions:
* [[#Wiki_actions|Wiki related actions]] to manage release notes.
 
=== report ===
 
Actions:
 
: Only read-only [[#Actions|common]] actions.
 
PUT /report/<GUID>/'''logs'''
 
Attach logs to the ''report''.
 
Sends:
: Attached logs with application/octet-stream MIME type.
 
Events:
: {{Code|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:
* [[#Wiki_actions|Wiki related actions]] to manage object description.
 
=== comment ===
 
=== event ===
 
Actions:
: Only read-only [[#Actions|common]] actions.


== Getting involved ==
== Getting involved ==


{{:Sugar_Network/Feedback}}
{{:Sugar_Network/Feedback}}
== 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/go/Sugar_Network/API"