Sugar Labs

Changes

Sugar Network/API (view source)

Revision as of 02:49, 13 March 2013

1,261 bytes removed ,  02:49, 13 March 2013
no edit summary
Line 30: Line 30:  
* [http://api-testing.network.sugarlabs.org/ api-testing.network.sugarlabs.org]<br>Recent stable release with data used in pilots; do not create temporal content here, use development server instead;
 
* [http://api-testing.network.sugarlabs.org/ api-testing.network.sugarlabs.org]<br>Recent stable release with data used in pilots; do not create temporal content here, use development server instead;
   −
* [http://localhost:5001/ localhost:5001]<br>default url to get access to [[#Local_access|local data]] served from local application.
+
* [http://localhost:5001/ localhost:5001]<br>default url to get access to [[#Client_proxy|local proxy]] provided from user side application.
    
== Sugar Network resources ==
 
== Sugar Network resources ==
Line 38: Line 38:  
=== Authentication ===
 
=== Authentication ===
   −
Right now, the only way to be authenticated on a Sugar Network server is running [[Platform_Team/Sugar_Network/Implementation#sugar-network-client|local application]] on client side and using the API it [[#Local_access|provides]].
+
Right now, the only way to be authenticated on a Sugar Network server is running [[Platform_Team/Sugar_Network/Implementation#sugar-network-client|local application]] on client side and using the API it [[#Client_proxy|provides]].
    
''TODO''
 
''TODO''
Line 168: Line 168:  
* {{Code|values}} an array of {{Code|timestamp, row}} tuples when {{Code|row}} is a dictionary of database field names and values.
 
* {{Code|values}} an array of {{Code|timestamp, row}} tuples when {{Code|row}} is a dictionary of database field names and values.
   −
== Local access ==
+
== Client proxy ==
   −
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 [[Platform_Team/Sugar_Network/Implementation#sugar-network-client|local process]] launched beforehand. The reasons to provide API from local host:
+
The reasons to proxy Sugar Network data on users side:
   −
* Provide assess to [[#Mountpoints|original local]] Sugar Network data;
+
* Seamless support offline workflow;
−
* Transparent treating of [[#Cloned_resources|offline accessible]] Sugar Network remote data;
+
* Provide user side features like cloning or launching software from the Sugar Network.
−
* Be a unified (with network server API) [[wikipedia:Inter-process_communication|IPC]] method to Sugar Network client process.
     −
=== Mountpoints ===
+
Proxying happens by providing the same Sugar Network API (with some extra functionality, see below) from
 +
[[Platform_Team/Sugar_Network/Implementation#sugar-network-client|local process]] launched beforehand.
   −
To differentiate what particular Sugar Network source is needed, requests might have {{Code|mountpoint}} argument which can be one of the following values:
+
=== Offline case ===
   −
* {{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);
+
Being connected to a Sugar Network server, local proxy provides original Sugar Network content. If connections is lost, proxy will switch to local Sugar Network storage and continues working. Any content created in offline mode will be uploaded to the server after getting connection back.
−
* {{Code|~}}<br>Local Sugar Network content located in {{Code|~/.sugar/''PROFILE''/network}} directory;
  −
* {{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}}.
  −
 
  −
There are the following mountpoints related commands:
  −
 
  −
'''GET''' /?cmd='''mounts'''
  −
 
  −
Returns a list of all accessible mountpoints. List items are dictionaries with the following keys:
  −
 
  −
* {{Code|mountpoint}}, mountpoint;
  −
* {{Code|name}}, i18n name of the mountpoint;
  −
* {{Code|private}}, boolean flag; {{Code|True}} if the mountpoint is accessible only from localhost.
      
=== Cloned resources ===
 
=== Cloned resources ===
   −
{{Code|/}} mountpoint resources might be cloned to local storage to be available in offline and out of  
+
Sugar Network resources might be cloned to local storage to be available in offline and out of  
 
Sugar Network.
 
Sugar Network.
   Line 205: Line 193:  
* ''Artifact'' resources<br>artifact 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:
+
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|favorite}} ''bool''<br>resources bookmarked by local user; bookmarked [and cloned] activities will appear in Home View in Sugar Shell;
Line 222: Line 210:  
=== Launch activities ===
 
=== Launch activities ===
   −
All activities, not only from {{Code|~}} mountpoint, can be launched as-is.
+
All activities can be launched as-is.
    
  '''GET''' /context/''GUID''?cmd='''launch'''[&args=''ARG''][&activity_id=''ACTIVITY_ID''][&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'']
Line 233: Line 221:  
* {{Code|NO_SPAWN}}, if specified, HTTP connection will not be closed until exiting activity process.
 
* {{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 [with further garbage collecting]. It is possible that during preparing for launching will be installed activity dependencies.
+
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].
    
=== Access to the Journal ===
 
=== Access to the Journal ===
Line 247: Line 235:  
== Usage ==
 
== Usage ==
   −
Being HTTP based, Sugar Network API can be used in any way how regular HTTP requests can be handled. But for command-line access, there is a handy tool, {{Code|sugar-network}}, that takes care about Sugar Network specific like lunching local API (if it is not already available) to get access to [[#Local_access|local data]].
+
Being HTTP based, Sugar Network API can be used in any way how regular HTTP requests can be handled. But for command-line access, there is a handy tool, {{Code|sugar-network}}, that takes care about Sugar Network specific like lunching local API (if it is not already available) to get access to [[#Client_proxy|local proxy]].
    
The sugar-network command-line format is, call {{Code|sugar-network --help}} for more detailed info:
 
The sugar-network command-line format is, call {{Code|sugar-network --help}} for more detailed info:
Retrieved from "https://wiki.sugarlabs.org/go/Special:MobileDiff/86656"