Sugar Network/API: Difference between revisions

Line 198:

The reasons to proxy Sugar Network data on users side:

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

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

* [[#Launching|One-click launch]] Sugar activities hosted on Sugar Network.

Line 204:

[[Platform_Team/Sugar_Network/Implementation#sugar-network-client|local process]] launched beforehand.

=== Offline ~~case~~ ===

=== Offline mode ===

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.

Line 210:

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

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

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

* ~~'''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.

* Checked-in Contexts<br>to keep most recent Context (for ''activity'' and ''book'' types) version in local storage to make it available in offline; note that there is no need in checking-in to speedup online lunch, versions are being [[#Launching|cached]] anyway; these Contexts will be marked by {{Code|checkin}} value in the ''Context.layer'' property.

To control users preferences there are special API commands:

Line 220:

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

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

Set favorite status.

'''~~PUT~~''' /context/''GUID''?cmd='''~~clone~~'''~~[&spawn]~~

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

~~Change cloning~~ status ~~for~~ the specified ~~context. {{Code|PUT}} content should be cloning status~~. By default, the command will return streamed ''text/event-stream'' MIME type data to monitor the ~~whole cloning process~~. If the {{Code|spawn}} argument is specified, the command will exit immediately with [[#Notifications|asynchronous sending]] ~~cloning~~ events.

Unset favorite status.

'''PUT''' /context/''GUID''?cmd='''checkin'''[&spawn]

Check-in the specified Context. By default, the command will return streamed ''text/event-stream'' MIME type data to monitor the progress. If the {{Code|spawn}} argument is specified, the command will exit immediately with [[#Notifications|asynchronous sending]] progress events.

'''DELETE''' /context/''GUID''?cmd='''checkin'''

Checkout the Context.

=== Launching ===

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

Sugar Network Contexts (for ''activity'' and ''book'' types) can be launched as-is. The launching process is implicit and includes selecting the most recent (and appropriate for software contexts) version, downloading bundles from the Sugar Network, installing missed [[Sugar_Network/Recipe_Specification#Dependencies|software dependencies]], execution itself. All downloaded bundles will be cached [with further garbage collecting] to speedup further launching.

Sugar activities ~~(with {{Code|activity}} value in the ''Context.type'' property)~~ will be directly executed. ~~Non-software contexts~~ will be opened in the proper application according to its ~~''Implementation.mime_type''~~.

Sugar activities will be directly executed. Book Contexts will be opened in the proper application according to its MIME type.

'''GET''' /context/''GUID''?cmd='''launch'''[&args=''ARG''][&activity_id=''ACTIVITY_ID''][&object_id=''OBJECT_ID''][&uri=''URI''][&~~context~~=''~~CONTEXT~~''][&spawn]

'''GET''' /context/''GUID''?cmd='''launch'''[&args=''ARG''][&activity_id=''ACTIVITY_ID''][&object_id=''OBJECT_ID''][&uri=''URI''][&app=''APP''][&spawn]

Arguments that make sense only for Sugar activities:

Line 243:

Line 255:

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

Arguments that make sense only for ~~non-software contexts~~:

Arguments that make sense only for books:

* {{Code|~~CONTEXT~~}}, specify application ''Context'' to open the ~~launching implementation~~ by; if omitted, the system will try to find most appropriate option, among all existing software ~~contexts, using ''Context.mime_types'' property~~.

* {{Code|APP}}, specify application Context to open the book by; if omitted, the system will try to find most appropriate option, among all existing software Contexts.

Common arguments:

@@ Line 198: / Line 198: @@
 The reasons to proxy Sugar Network data on users side:
-* Seamless support [[#Offline case|offline workflow]];
+* Seamless support [[#Offline mode|offline workflow]];
 * [[#Launching|One-click launch]] Sugar activities hosted on Sugar Network.
@@ Line 204: / Line 204: @@
 [[Platform_Team/Sugar_Network/Implementation#sugar-network-client|local process]] launched beforehand.
-=== Offline case ===
+=== Offline mode ===
 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.
@@ Line 210: / Line 210: @@
 Besides, local Sugar Network storage will be reused to keep users preferences, such as:
-* '''favorite''' contexts<br>to select preferred ''Context'' resources; these contexts will be marked by {{Code|favorite}} value in the ''Context.layer'' property;
+* Favorited Contexts<br>to select preferred ''Context'' resources; these Contexts will be marked by {{Code|favorite}} value in the ''Context.layer'' property;
-* '''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.
+* Checked-in Contexts<br>to keep most recent Context (for ''activity'' and ''book'' types) version in local storage to make it available in offline; note that there is no need in checking-in to speedup online lunch, versions are being [[#Launching|cached]] anyway; these Contexts will be marked by {{Code|checkin}} value in the ''Context.layer'' property.
 To control users preferences there are special API commands:
@@ Line 220: / Line 220: @@
   '''PUT''' /context/''GUID''?cmd='''favorite'''
-Change favorite status. {{Code|PUT}} content should be favorite status.
+Set favorite status.
-<div id="PUT_clone"></div>
+<div id="DELETE_favorite"></div>
-  '''PUT''' /context/''GUID''?cmd='''clone'''[&spawn]
+  '''DELETE''' /context/''GUID''?cmd='''favorite'''
-Change cloning status for the specified context. {{Code|PUT}} content should be cloning status. By default, the command will return streamed ''text/event-stream'' MIME type data to monitor the whole cloning process. If the {{Code|spawn}} argument is specified, the command will exit immediately with [[#Notifications|asynchronous sending]] cloning events.
+Unset favorite status.
+<div id="PUT_checkin"></div>
+ '''PUT''' /context/''GUID''?cmd='''checkin'''[&spawn]
+Check-in the specified Context. By default, the command will return streamed ''text/event-stream'' MIME type data to monitor the progress. If the {{Code|spawn}} argument is specified, the command will exit immediately with [[#Notifications|asynchronous sending]] progress events.
+<div id="DELETE_checkin"></div>
+ '''DELETE''' /context/''GUID''?cmd='''checkin'''
+Checkout the Context.
 === Launching ===
-Sugar Network ''Contexts'' can be launched as-is. The launching process is implicit and includes selecting the most recent (and appropriate for software contexts) ''Implementation'', downloading bundles from the Sugar Network, installing missed [[Sugar_Network/Recipe_Specification#Dependencies|software dependencies]], execution. All downloaded implementations will be cached [with further garbage collecting] to speedup further launching.
+Sugar Network Contexts (for ''activity'' and ''book'' types) can be launched as-is. The launching process is implicit and includes selecting the most recent (and appropriate for software contexts) version, downloading bundles from the Sugar Network, installing missed [[Sugar_Network/Recipe_Specification#Dependencies|software dependencies]], execution itself. All downloaded bundles will be cached [with further garbage collecting] to speedup further launching.
-Sugar activities (with {{Code|activity}} value in the ''Context.type'' property) will be directly executed. Non-software contexts will be opened in the proper application according to its ''Implementation.mime_type''.
+Sugar activities will be directly executed. Book Contexts will be opened in the proper application according to its MIME type.
-  '''GET''' /context/''GUID''?cmd='''launch'''[&args=''ARG''][&activity_id=''ACTIVITY_ID''][&object_id=''OBJECT_ID''][&uri=''URI''][&context=''CONTEXT''][&spawn]
+  '''GET''' /context/''GUID''?cmd='''launch'''[&args=''ARG''][&activity_id=''ACTIVITY_ID''][&object_id=''OBJECT_ID''][&uri=''URI''][&app=''APP''][&spawn]
 Arguments that make sense only for Sugar activities:
@@ Line 243: / Line 255: @@
 * {{Code|URI}}, URL to resume if activity supports this functionality.
-Arguments that make sense only for non-software contexts:
+Arguments that make sense only for books:
-* {{Code|CONTEXT}}, specify application ''Context'' to open the launching implementation by; if omitted, the system will try to find most appropriate option, among all existing software contexts, using ''Context.mime_types'' property.
+* {{Code|APP}}, specify application Context to open the book by; if omitted, the system will try to find most appropriate option, among all existing software Contexts.
 Common arguments: