Sugar Network/API: Difference between revisions

Line 197:

The reasons to proxy Sugar Network data on users side:

* [[#Offline case|~~Seamless support]]~~ offline workflow;

* Seamless support [[#Offline case|offline workflow]];

* [[#Cloned resources|Easy download]] ~~Sugar Network resources~~;

* [[#Launching|Reliable launch]] Sugar activities hosted on Sugar Network.

* [[#~~Launch activities~~|Reliable launch]] Sugar activities hosted on Sugar Network.

Proxying happens by providing the same Sugar Network API (with some extra functionality, see below) from

Line 208:

Line 207:

Being connected to a Sugar Network server, local proxy provides original Sugar Network content. If the connection is lost, the proxy will switch to local Sugar Network storage and continue working. Any content created in offline mode will be uploaded to the server after getting a connection back.

~~=== Cloned resources ===~~

Besides, local Sugar Network storage will be reused to keep users preferences, such as:

~~Sugar Network~~ resources ~~might be cloned to local storage to~~ be ~~available~~ in ~~offline and out of~~

* '''favorite''' contexts<br>to select preferred ''Context'' resources; these contexts will be marked by {{Code|favorite}} value in the ''Context.layer'' property;

~~Sugar Network~~.

~~Cloning~~ is ~~available only for~~ the ~~following resources:~~

* '''cloned''' contexts<br>to keep most recent context ''Implementation'' in local storage to make it available in offline; note that there is no need in cloning to speedup online lunch, ''Implementations'' are being [[#Launching|cached]] anyway; these contexts will be marked by {{Code|clone}} value in the ''Context.layer'' property.

* ''Context'' with ''type'' property equal to ''activity''<br>most recent activity ''Implementation'' will be placed in the {{Code|~/Activities}} directory; note that there is no need in cloning activities before starting, it is possible to [[#Launch_activities|launch]] them directly;

To control users preferences there are special API commands:

* ''Context'' with ''type'' property equal 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 that make sense only for API provided from the local process:~~

* {{Code|favorite}} ''bool''<br>resources bookmarked by local user; bookmarked [and cloned] 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 ~~cloned content,~~ there are API commands:

'''PUT''' /~~''RESOURCE''~~/''GUID''?cmd='''favorite'''

'''PUT''' /context/''GUID''?cmd='''favorite'''

Change favorite status. {{Code|PUT}} content should be favorite status.

Line 234:

Line 223:

'''PUT''' /~~''RESOURCE''~~/''GUID''?cmd='''clone'''

'''PUT''' /context/''GUID''?cmd='''clone'''

Change cloning status for the specified ~~resource~~. {{Code|PUT}} content should be cloning status.

Change cloning status for the specified context. {{Code|PUT}} content should be cloning status. If cloned context is a Sugar activity, the command will create a symlink in {{Code||~/Activities}} directory to newly fetched implementation.

=== ~~Launch activities~~ ===

=== Launching ===

~~All~~ Sugar Network ~~activities~~ can be launched as-is.

Sugar Network ''Contexts'' can be launched as-is. The launching process is implicit and includes selecting most recent (and appropriate for software contexts) ''Implementation'', downloading bundles from the Sugar Network, execution. All downloaded implementations will be cached [with further garbage collecting] to speedup next launching.

Sugar activities (with {{Code|activity}} value in the ''Context.type'' property) will be directly executed after making sure that all [[Sugar_Network/Recipe_Specification#Dependencies|software dependencies]] are installed in the system. Non-software contexts will be opened in the proper application according to its ''Context.mime_type''.

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

* {{Code|NO_SPAWN}}, if specified, HTTP connection will not be closed until exiting activity process.

Arguments that make sense only for Sugar activities:

* {{Code|ARG}}, command line argument to pass to launched activities, repeat {{Code|ARG}} for each argument;

Line 249:

Line 244:

* {{Code|URI}}, URL to resume if activity supports this functionality;

* {{Code|COLOR}}, comma separated pair of Sugar colors to assign to activity object;

* {{Code|NO_SPAWN}}, if specified, HTTP connection will not be closed until exiting activity process.

Previously cloned activities will be launched as-is from {{Code|~/Activities}} directory. The rest of activities will be downloaded from the server and kept in cache directory [with further garbage collecting]. Besides, Sugar Network client application makes launch process reliable by solving software dependencies, e.g., missed packages will be installed using [[wikipedia:PackageKit|PackageKit]].

<!--

=== Access to the Journal ===

Line 262:

Line 255:

This kind of access might be useful when local applications cannot use DBus sugar-datastore API, e.g., [[wikipedia:Javascript|Javascript]] applications.

-->

== Usage ==

@@ Line 197: / Line 197: @@
 The reasons to proxy Sugar Network data on users side:
-* [[#Offline case|Seamless support]] offline workflow;
+* Seamless support [[#Offline case|offline workflow]];
-* [[#Cloned resources|Easy download]] Sugar Network resources;
+* [[#Launching|Reliable launch]] Sugar activities hosted on Sugar Network.
-* [[#Launch activities|Reliable launch]] Sugar activities hosted on Sugar Network.
 Proxying happens by providing the same Sugar Network API (with some extra functionality, see below) from
@@ Line 208: / Line 207: @@
 Being connected to a Sugar Network server, local proxy provides original Sugar Network content. If the connection is lost, the proxy will switch to local Sugar Network storage and continue working. Any content created in offline mode will be uploaded to the server after getting a connection back.
-=== Cloned resources ===
+Besides, local Sugar Network storage will be reused to keep users preferences, such as:
-Sugar Network resources might be cloned to local storage to be available in offline and out of
+* '''favorite''' contexts<br>to select preferred ''Context'' resources; these contexts will be marked by {{Code|favorite}} value in the ''Context.layer'' property;
-Sugar Network.
-Cloning is available only for the following resources:
+* '''cloned''' contexts<br>to keep most recent context ''Implementation'' in local storage to make it available in offline; note that there is no need in cloning to speedup online lunch, ''Implementations'' are being [[#Launching|cached]] anyway; these contexts will be marked by {{Code|clone}} value in the ''Context.layer'' property.
-* ''Context'' with ''type'' property equal to ''activity''<br>most recent activity ''Implementation'' will be placed in the {{Code|~/Activities}} directory; note that there is no need in cloning activities before starting, it is possible to [[#Launch_activities|launch]] them directly;
+To control users preferences there are special API commands:
-* ''Context'' with ''type'' property equal 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 that make sense only for API provided from the local process:
-* {{Code|favorite}} ''bool''<br>resources bookmarked by local user; bookmarked [and cloned] 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 cloned content, there are API commands:
 <div id="PUT_favorite"></div>
-  '''PUT''' /''RESOURCE''/''GUID''?cmd='''favorite'''
+  '''PUT''' /context/''GUID''?cmd='''favorite'''
 Change favorite status. {{Code|PUT}} content should be favorite status.
@@ Line 234: / Line 223: @@
 <div id="PUT_clone"></div>
-  '''PUT''' /''RESOURCE''/''GUID''?cmd='''clone'''
+  '''PUT''' /context/''GUID''?cmd='''clone'''
-Change cloning status for the specified resource. {{Code|PUT}} content should be cloning status.
+Change cloning status for the specified context. {{Code|PUT}} content should be cloning status. If cloned context is a Sugar activity, the command will create a symlink in {{Code||~/Activities}} directory to newly fetched implementation.
-=== Launch activities ===
+=== Launching ===
-All Sugar Network activities can be launched as-is.
+Sugar Network ''Contexts'' can be launched as-is. The launching process is implicit and includes selecting most recent (and appropriate for software contexts) ''Implementation'', downloading bundles from the Sugar Network, execution. All downloaded implementations will be cached [with further garbage collecting] to speedup next launching.
+Sugar activities (with {{Code|activity}} value in the ''Context.type'' property) will be directly executed after making sure that all [[Sugar_Network/Recipe_Specification#Dependencies|software dependencies]] are installed in the system. Non-software contexts will be opened in the proper application according to its ''Context.mime_type''.
   '''GET''' /context/''GUID''?cmd='''launch'''[&args=''ARG''][&activity_id=''ACTIVITY_ID''][&object_id=''OBJECT_ID''][&uri=''URI''][&color=''COLOR''][&no_spawn=''NO_SPAWN'']
+* {{Code|NO_SPAWN}}, if specified, HTTP connection will not be closed until exiting activity process.
+Arguments that make sense only for Sugar activities:
 * {{Code|ARG}}, command line argument to pass to launched activities, repeat {{Code|ARG}} for each argument;
@@ Line 249: / Line 244: @@
 * {{Code|URI}}, URL to resume if activity supports this functionality;
 * {{Code|COLOR}}, comma separated pair of Sugar colors to assign to activity object;
-* {{Code|NO_SPAWN}}, if specified, HTTP connection will not be closed until exiting activity process.
-Previously cloned activities will be launched as-is from {{Code|~/Activities}} directory. The rest of activities will be downloaded from the server and kept in cache directory [with further garbage collecting]. Besides, Sugar Network client application makes launch process reliable by solving software dependencies, e.g., missed packages will be installed using [[wikipedia:PackageKit|PackageKit]].
+<!--
 === Access to the Journal ===
@@ Line 262: / Line 255: @@
 This kind of access might be useful when local applications cannot use DBus sugar-datastore API, e.g., [[wikipedia:Javascript|Javascript]] applications.
+-->
 == Usage ==