Sugar Labs

Sugar Network/API: Difference between revisions

← Older editNewer edit →
Line 179: Line 179:
== Local access ==
== Local access ==


If [[#Sugar_Network_resources|already mentioned]] resources are being provided from a network server, it is possible to get access to localhost resources served using the same RESTful API by local process launched beforehand. The reasons to provide API from local host:
If [[#Sugar_Network_resources|already mentioned]] resources are being provided from a network server, it is possible to get access to localhost resources served using the same API by local process launched beforehand. The reasons to provide API from local host:


* Provide assess to [[#Mountpoints|local]] Sugar Network data;
* Provide assess to [[#Mountpoints|original local]] Sugar Network data;
* Transparent treating of [[#Offline_activities|offline accessible]] Sugar activities;
* Transparent treating of [[#Cloned_resources|offline accessible]] Sugar Network remote data;
* Be a unified (with network server API) [[wikipedia:Inter-process_communication|IPC]] method for local applications.
* Be a unified (with network server API) [[wikipedia:Inter-process_communication|IPC]] method to Sugar Network client process.


=== Mountpoints ===
=== Mountpoints ===
Line 189: Line 189:
To differentiate what particular Sugar Network source is needed, requests might have {{Code|mountpoint}} argument which can be one of the following values:
To differentiate what particular Sugar Network source is needed, requests might have {{Code|mountpoint}} argument which can be one of the following values:


* {{Code|/}}, default mountpoint if argument was not specified; get access to remote resources, i.e., local API provider is a kind of proxy to the remote one;
* {{Code|/}}<br>Default mountpoint if argument was not specified; get access to remote resources, i.e., local API provider is a kind of proxy to a network server; before proxying client requests, local API provider authenticates users on a network server (for now, it is the only way to be authenticated on remote server);
 
* {{Code|~}}<br>Local Sugar Network content located in {{Code|~/.sugar/''PROFILE''/network}} directory;
* {{Code|~}}, Sugar Network content located in {{Code|~/.sugar/''PROFILE''/network}} directory; this mountpoint might support special use cases, see the rest of this text;
* {{Code|''PATH''}}<br>Absolute path in local files system to a directory with Sugar Network content, e.g., it might be content on mounted disk, {{Code|/media/DISK}}.
 
* {{Code|''PATH''}}, absolute path in local files system to a directory with Sugar Network content, e.g., it might be content on mounted disk, {{Code|/media/DISK}}.
 
The mountpoint {{Code|/}}, in addition to proxing user requests to a Sugar Network server, provides the following functionality:
 
* user is already authenticated, e.g., it is possible to change content on Sugar Network server.


There are the following mountpoints related commands:
There are the following mountpoints related commands:
Line 209: Line 203:
* {{Code|private}}, boolean flag; {{Code|True}} if the mountpoint is accessible only from localhost.
* {{Code|private}}, boolean flag; {{Code|True}} if the mountpoint is accessible only from localhost.


=== Offline activities ===
=== Cloned resources ===


To get access to {{Code|/}} mountpoint activities even if there is no server connection, activities need to be accessible from {{Code|~}} mountpoint. There are special ''Context'' properties (on all mountpoints) that relate only to offline activities:
{{Code|/}} mountpoint resources might be cloned to local storage to be available in offline and out of
Sugar Network.


* {{Code|keep}}<br>Bookmarked context which metadata is accessible from {{Code|~}} mountpoint;
Cloning is available only for the following resources:
* {{Code|keep_impl}}<br>Most recent version of the corresponding ''Context'' is accessible from {{Code|~}} mountpoint being placed to {{Code|~/Activities}} directory;
* {{Code|position}}<br>A tuple of integer values with X and Y coordinates of activity icon position in Sugar Shell's Home view.


All properties are writable, so, it is possible to set {{Code|keep_impl}} property to {{Code|True}} for a ''Context'' on {{Code|/}} mountpoint to make sure that after going offline, this ''Context'' will remain runnable. The same true for clearing {{Code|keep_impl}} as well.
* ''Context'' with ''type'' property equals to ''activity''<br>most recent activity ''Implementation'' will be placed to {{Code|~/Activities}} directory;
* ''Context'' with ''type'' property equals to ''content''<br>most recent content ''Implementation'' will be stored in Sugar Journal;
* ''Artifact'' resources<br>artifact will be stored in Sugar Journal.
 
To track what data is cloned, there are read-only resource properties (for both {{Code|/}} and {{Code|~}} mountpoints) that make sense only for API provided from the local process:
 
* {{Code|favorite}} ''bool''<br>resources bookmarked by local user; bookmarked activities will appear in Home View in Sugar Shell;
* {{Code|clone}} ''int''<br>cloning status: {{Code|0}}, not cloned; {{Code|1}}, cloning is in progress; {{Code|2}} resource is cloned.
 
To control cloning, there are API commands:
 
'''PUT''' /''RESOURCE''/''GUID''?cmd='''favorite'''
 
Change favorite status. {{Code|PUT}} content should be favorite status.
 
'''PUT''' /''RESOURCE''/''GUID''?cmd='''clone'''[&force=FORCE]
 
Change cloning status for the specified resource. {{Code|PUT}} content should be cloning status. If {{Code|FORCE}} is passed, cloning will happen even if local copy already exists.


=== Launch activities ===
=== Launch activities ===
Line 223: Line 233:
All activities, not only from {{Code|~}} mountpoint, can be launched as-is.
All activities, not only from {{Code|~}} mountpoint, can be launched as-is.


  '''GET''' /context/''GUID''?cmd='''launch'''[&args=''ARG''][&activity_id=''ACTIVITY_ID''][&context=''CONTEXT''][&object_id=''OBJECT_ID''][&uri=''URI''][&color=''COLOR''][&no_spawn=''NO_SPAWN'']
  '''GET''' /context/''GUID''?cmd='''launch'''[&args=''ARG''][&activity_id=''ACTIVITY_ID''][&object_id=''OBJECT_ID''][&uri=''URI''][&color=''COLOR''][&no_spawn=''NO_SPAWN'']


* {{Code|ARG}}, command line argument to pass to launched activities, repeat {{Code|ARG}} for each argument;
* {{Code|ARG}}, command line argument to pass to launched activities, repeat {{Code|ARG}} for each argument;
* {{Code|ACTIVITY_ID}}, internal activity id which will be auto set if omitted;
* {{Code|ACTIVITY_ID}}, internal activity id which will be auto set if omitted;
* {{Code|OBJECT_ID}}, id to resume Journal object; it [[#Resume_activities|might be]] GUID of a Sugar Network resource as well;
* {{Code|OBJECT_ID}}, Journal object id to resume;
* {{Code|CONTEXT}}, Sugar Network ''Context'' to resume, see [[#Resume_activities|Resume activities]] for details;
* {{Code|URI}}, URL to resume if activity supports this functionality;
* {{Code|URI}}, URL to resume if activity supports this functionality;
* {{Code|COLOR}}, coma separated pair of Sugar colors to assign to activity object;
* {{Code|COLOR}}, coma separated pair of Sugar colors to assign to activity object;
Line 234: Line 243:


{{Code|~}} mountpoint activities will be launched as-is from {{Code|~/Activities}} directory. For {{Code|/}} mountpoint, activities will be downloaded from the server and kept in cache directory. It is possible that during preparing for launching will be installed activity dependencies.
{{Code|~}} mountpoint activities will be launched as-is from {{Code|~/Activities}} directory. For {{Code|/}} mountpoint, activities will be downloaded from the server and kept in cache directory. It is possible that during preparing for launching will be installed activity dependencies.
=== Resume activities ===
While [[#Launch_activities|launching]] it is possible to open various objects. There are several use-cases:
* Resume local Journal object<br>{{Code|OBJECT_ID}} launch parameter is set to Journal id and {{Code|CONTEXT}} is not set;
* Resume Sugar Network ''Artifact'' resources<br>{{Code|OBJECT_ID}} launch parameter is set to proper ''Artifact'' GUID and {{Code|CONTEXT}} to ''Context'' GUID the artifact belongs to;
* Resume Sugar Network ''Context'' resources<br>{{Code|OBJECT_ID}} is not set and {{Code|CONTEXT}} is set to ''Context'' GUID to find most recent ''Implementation'' to resume.
For the last two cases, particular objects will be downloaded and placed to the Journal (with keeping GUIDs as Journal IDs) to make it possible to open from from launched activity.


=== Access to the Journal ===
=== Access to the Journal ===
Retrieved from "https://wiki.sugarlabs.org/go/Sugar_Network/API"