Sugar Labs

Sugar Network/API: Difference between revisions

← Older editNewer edit →
No edit summary
Line 5: Line 5:
To better understand this API, see technical explanation of the [[Platform_Team/Sugar_Network/Architecture#Conceptual_level|conceptual level]] and [[Platform_Team/Sugar_Network/Objects_model|objects model]] in particular.
To better understand this API, see technical explanation of the [[Platform_Team/Sugar_Network/Architecture#Conceptual_level|conceptual level]] and [[Platform_Team/Sugar_Network/Objects_model|objects model]] in particular.


The API operates with [[#Resources|resources]] that are collections of objects. All objects are identified by global unique identifiers, GUIDs. Resources might support [[#Actions|common actions]]. While processing requests, server might generate [[#events|events]]. There are [[#Events|common events]] that all resources might generate.
The API operates with [[Sugar Network]] [[#Sugar_Network_resources|resources]] that are collections of objects. All objects are identified by global unique identifiers, GUIDs. Resources might support [[#Common_actions|common actions]]. While processing requests, server might generate [[#Notifications|events]]. Besides, API provides [[#Additional_resources|extra resources]] that are not [[Sugar Network]] objects.


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:
Line 22: Line 22:
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.


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.
In [[#Common_actions|most cases]], 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. In the rest of cases, response might be variable.


== Resources ==
== Sugar Network resources ==


{{:Platform_Team/Sugar_Network/Objects_model}}
{{:Platform_Team/Sugar_Network/Objects_model}}


== Actions ==
=== Common actions ===


List of actions common of all resources.
List of actions common of all resources.
Line 86: Line 86:
:* property value in JSON notation.
:* property value in JSON notation.


== packagekit-backend-presolve ==
=== Notifications ===
 
It is possible to subscribe to server events. Notification will happen using HTML5 [[wikipedia:Server-sent_events|Server-sent events]].
 
To start subscription, send the following request:
 
'''GET''' /?cmd=subscribe[&only_commits=1]
 
Where:
* {{Code|only_commits}},<br>subscribers can be notified only with ''commit'' events; that is useful to minimize interactions between server and clients.
 
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:
 
* {{Code|event}}<br>event type.
 
== Additional resources ==
 
In addition to direct Sugar Network [[#Resources|resources]], API provides related content.
 
=== packagekit-backend-presolve ===


In order to provide GNU/Linux-distribution-agnostic launches of activities, Sugar Network API supports [[Platform_Team/packagekit-backend-presolve|packagekit-backend-presolve]] users.
In order to provide GNU/Linux-distribution-agnostic launches of activities, Sugar Network API supports [[Platform_Team/packagekit-backend-presolve|packagekit-backend-presolve]] users.
Line 102: Line 121:


[[Sugar Network]] supports a metadata ''database'' for all packages that are being used as dependencies for activities it provides (see ''Packages'' project using one of the existing [[Sugar_Network#Try_it|Sugar Network clients]]). Every entry in the ''database'' contains a map of native package names for a particular GNU/Linux distribution. So, activities mention only the ''database'' entry name as a dependency. [[Sugar Network]] will automatically generate dependency graphs for packagekit-backend-presolve using the ''metadata'' database. Afterwards, on the launch side, the ''database'' entry name will be resolved to a package name according to the local distribution and it will be passed to the PackageKit (on XO laptops, packagekit-backend-presolve will be used; on regular platforms, the default PackageKit back-end is used).
[[Sugar Network]] supports a metadata ''database'' for all packages that are being used as dependencies for activities it provides (see ''Packages'' project using one of the existing [[Sugar_Network#Try_it|Sugar Network clients]]). Every entry in the ''database'' contains a map of native package names for a particular GNU/Linux distribution. So, activities mention only the ''database'' entry name as a dependency. [[Sugar Network]] will automatically generate dependency graphs for packagekit-backend-presolve using the ''metadata'' database. Afterwards, on the launch side, the ''database'' entry name will be resolved to a package name according to the local distribution and it will be passed to the PackageKit (on XO laptops, packagekit-backend-presolve will be used; on regular platforms, the default PackageKit back-end is used).
== Notifications ==
It is possible to subscribe to server events. Notification will happen using HTML5 [[wikipedia:Server-sent_events|Server-sent events]].
To start subscription, send the following request:
'''GET''' /?cmd=subscribe[&only_commits=1]
Where:
* {{Code|only_commits}},<br>subscribers can be notified only with ''commit'' events; that is useful to minimize interactions between server and clients.
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:
* {{Code|event}}<br>event type.


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


{{:Sugar_Network/Feedback}}
{{:Sugar_Network/Feedback}}
Retrieved from "https://wiki.sugarlabs.org/go/Sugar_Network/API"