Sugar Network/API: Difference between revisions

Line 159:

== Local resources ==

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. ~~Local Sugar Network resources are [[#Sugar_Network_resources|the same]] structure data but located on~~ local host~~, e.g., in user's home directory or on mounted removable device.~~

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:

~~This kind of access might be useful when local applications cannot use regular IPC mechanisms, e.g., D-Bus, to get access~~ to local ~~resources. For example, local~~ [[wikipedia:~~Javascript~~|~~Javascript~~]] applications.

* Provide assess to [[#Mountpoints|local]] Sugar Network data;

* Transparent treating of [[#Offline_activities|offline accessible]] Sugar activities;

* Be a unified (with network server API) [[wikipedia:Inter-process_communication|IPC]] method for local applications.

=== Mountpoints ===

To differentiate what particular Sugar Network source is needed, ~~all~~ requests ~~should~~ have {{Code|mountpoint}} argument which ~~might~~ 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;

Line 187:

Line 189:

* {{Code|private}}, boolean flag; {{Code|True}} if the mountpoint is accessible only from localhost.

~~<!--~~=== ~~Access to the Journal~~ ===

=== Offline activities ===

It is possible to ~~get access~~ to ~~local Sugar Journal using~~ ''~~Artifact~~'' ~~resources~~ from {{Code|~}} mountpoint. ~~All~~ ''~~Artifact~~'' [[#~~Sugar_Network_resources~~|~~properties~~]] ~~represent particular Journal entity attributes when arbitrary attributes~~, ~~e.g.~~, ~~create by particular~~ Sugar ~~Activity~~, ~~are being collected in~~ {{Code|~~traits~~}} ~~property~~. It is possible to ~~work with~~ local ''Artifact'' resources ~~like any regular~~ Sugar Network ~~one~~, e.g., ~~make a search~~.~~-->~~

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 control what activities exist on {{Code|~}} mountpoint:

* {{Code|keep}} Bookmarked context which metadata is accessible from {{Code|~}} mountpoint;

* {{Code|keep_impl}} Most recent version of the corresponding ''Context'' is accessible from {{Code|~}} mountpoint being placed to {{Code|~/Activities}} directory.

Both 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.

=== Launch activities ===

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'']

* {{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|OBJECT_ID}}, id to resume Journal object; it [[#Resume_activities|might be]] GUID of a Sugar Network resource as well;

* {{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|COLOR}}, coma 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.

{{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 {{Code|OBJECT_ID}} launch parameter is set to Journal id and {{Code|CONTEXT}} is not set;

* Resume Sugar Network ''Artifact'' resources {{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 {{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 ===

It is possible to get access to local Sugar Journal using special, ''journal'', resource. API to Journal is restricted only to read-only access:

'''GET''' /journal?offset=''INTEGER''&limit=''INTEGER''[&query=''STRING''][&order_by=<nowiki>[+|-]</nowiki>''PROP''][&''QUERY_PROP''=''VALUE''[&...]]

'''GET''' /journal/''JOURNAL_ID''[?reply=''PROP''[,..]]

'''GET''' /journal/''JOURNAL_ID''/''PROPERTY''

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

== Getting involved ==

@@ Line 159: / Line 159: @@
 == Local resources ==
-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. Local Sugar Network resources are [[#Sugar_Network_resources|the same]] structure data but located on local host, e.g., in user's home directory or on mounted removable device.
+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:
-This kind of access might be useful when local applications cannot use regular IPC mechanisms, e.g., D-Bus, to get access to local resources. For example, local [[wikipedia:Javascript|Javascript]] applications.
+* Provide assess to [[#Mountpoints|local]] Sugar Network data;
+* Transparent treating of [[#Offline_activities|offline accessible]] Sugar activities;
+* Be a unified (with network server API) [[wikipedia:Inter-process_communication|IPC]] method for local applications.
 === Mountpoints ===
-To differentiate what particular Sugar Network source is needed, all requests should have {{Code|mountpoint}} argument which might 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;
@@ Line 187: / Line 189: @@
 * {{Code|private}}, boolean flag; {{Code|True}} if the mountpoint is accessible only from localhost.
-<!--=== Access to the Journal ===
+=== Offline activities ===
-It is possible to get access to local Sugar Journal using ''Artifact'' resources from {{Code|~}} mountpoint. All ''Artifact'' [[#Sugar_Network_resources|properties]] represent particular Journal entity attributes when arbitrary attributes, e.g., create by particular Sugar Activity, are being collected in {{Code|traits}} property. It is possible to work with local ''Artifact'' resources like any regular Sugar Network one, e.g., make a search.-->
+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 control what activities exist on {{Code|~}} mountpoint:
+* {{Code|keep}}<br>Bookmarked context which metadata is accessible from {{Code|~}} mountpoint;
+* {{Code|keep_impl}}<br>Most recent version of the corresponding ''Context'' is accessible from {{Code|~}} mountpoint being placed to {{Code|~/Activities}} directory.
+Both 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.
+=== Launch activities ===
+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'']
+* {{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|OBJECT_ID}}, id to resume Journal object; it [[#Resume_activities|might be]] GUID of a Sugar Network resource as well;
+* {{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|COLOR}}, coma 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.
+{{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 ===
+It is possible to get access to local Sugar Journal using special, ''journal'', resource. API to Journal is restricted only to read-only access:
+ '''GET''' /journal?offset=''INTEGER''&limit=''INTEGER''[&query=''STRING''][&order_by=<nowiki>[+|-]</nowiki>''PROP''][&''QUERY_PROP''=''VALUE''[&...]]
+ '''GET''' /journal/''JOURNAL_ID''[?reply=''PROP''[,..]]
+ '''GET''' /journal/''JOURNAL_ID''/''PROPERTY''
+This kind of access might be useful when local applications cannot use DBus sugar-datastore API, e.g., [[wikipedia:Javascript|Javascript]] applications.
 == Getting involved ==
 {{:Sugar_Network/Feedback}}