Sugar Labs

Sugar Network/API: Difference between revisions

← Older editNewer edit →
Line 39: Line 39:


{{:Sugar_Network/Resources}}
{{:Sugar_Network/Resources}}
== Nodes ==
This is an API provided by Sugar Network nodes.


=== Authentication ===
=== Authentication ===
Line 137: Line 141:
* raw data or redirection for BLOB properties.
* raw data or redirection for BLOB properties.


<div id="HEAD-property"></div>
=== Aggregated properties ===
 
[[Sugar_Network/Resources#Property_types|Aggregated]] properties have special API to treat their content.
 
<div id="POST-aggproperty"></div>
 
'''POST''' /''RESOURCE''/''GUID''/''PROP''
 
Submit new item. The command returns an id for newly created aggregated item. Depending on particular property, new items might be created not only by object's authors.
 
<div id="PUT-aggproperty"></div>
 
'''PUT''' /''RESOURCE''/''GUID''/''PROP''/''ID''
 
Update existing aggregated item. Depending on particular property, the command is allowed either to object's authors or to aggregated item submitter.
 
<div id="DELETE-aggproperty"></div>
 
'''DELETE''' /''RESOURCE''/''GUID''/''PROP''/''ID''
 
Delete existing aggregated item. Depending on particular property, the command is allowed either to object's authors or to aggregated item submitter.
 
=== Download releases ===
 
To easy download Context [[Sugar_Network/Resources#context-releases|releases]] and avoid reading raw ''Context.releases'' property, there are special high-level API commands.
 
<div id="GET-solve"></div>
 
'''GET''' /context/''GUID''?cmd='''solve'''[&requires=''DEPENDENCY''][&lsb_id=''LSB_ID''][&lsb_release=''LSB_RELEASE'']


'''HEAD''' /''RESOURCE''/''GUID''/''PROP''
The command returns information about what particular releases should be downloaded depending on provided requirements. This command might return not only one release, e.g., activities might have dependencies either system packages or another Sugar Network Contexts.


Return property metadata for particular resource object. In addition to regular HTTP header properties, the command will return Sugar Network property metadata in header keys prefixed by {{Code|X-SN-}}.
Solving requirements might be:


=== Download activities ===
* {{Code|DEPENDENCY}}, solved release should conform the specified [[Sugar_Network/Recipe_Specification#Dependencies|dependencies]]; the argument might be multiple;
* {{Code|LSB_ID}}, if Context releases depend on system packages, specify the [[Wikipedia:Linux_Standard_Base|LSB]] distributor id to consider while choosing particular packages;
* {{Code|LSB_RELEASE}}, if Context releases depend on system packages, specify the [[Wikipedia:Linux_Standard_Base|LSB]] release number of the distribution to consider while choosing particular packages.


To download a Sugar Activity bundle from the Sugar Network, it is required to find out the GUID of ''Implementation'' with the required activity version. To make this process more convenient for users, there is special command that requires only ''Context'' GUID (which is, in most cases, equal to Sugar Activity bundle id).
The resulting info is a JSON object with keys equal to Context guids and value objects for chosen release with the following keys:


'''GET''' /context/''GUID''?cmd='''clone'''[&requires=''DEPENDENCY''][&''PROP''=''VALUE'']
* {{Code|blob}}, bundle [[Sugar_Network/Resources#Property_types|digest]] to download;
'''HEAD''' /context/''GUID''?cmd='''clone'''[&requires=''DEPENDENCY''][&''PROP''=''VALUE'']
* {{Code|version}}, chosen version number;
* {{Code|title}}, the ''Context.title'' value;
* {{Code|command}}, a command to launch the bundle, only for Sugar activities.


Using passed parameters, this command finds out proper ''Implementation'' and returns its bundle. If there are more than one implementation, the most recent version will be chosen.
<div id="GET-solve"></div>


Command parameters might be any [[Sugar_Network/Resources|Implementation]] property values, such as ''stability'' or ''version'', to filter implementations by. The ''requires'' parameter has a special meaning, it is intended to select an implementation by its [[Sugar_Network/Recipe_Specification#requires|dependency list]]. {{Code|DEPENDENCY}} value is multiple and should conform Sugar Network [[Sugar_Network/Recipe_Specification#Dependencies|recipe specification]].
'''GET''' /context/''GUID''?cmd='''clone'''[&requires=''DEPENDENCY''][&lsb_id=''LSB_ID''][&lsb_release=''LSB_RELEASE'']


The {{Code|'''HEAD'''}} command will not return bundle itself but rather its [[#HEAD-property|metadata]] combined with selected ''Implementation'' properties.
Like the [[#GET-solve|solve]] command, ''clone'' makes a solution but returns bundle itself, i.e., it ignores possible dependencies.


=== Upload new releases ===
=== Upload releases ===


The regular procedure to upload new Implementation objects is using the {{Code|POST /implementation}} API command with specifying new Implementation properties and {{Code|PUT}}'ing new bundle itself. To make this process shorter, there is a special API command.
To easy upload Context [[Sugar_Network/Resources#context-releases|releases]] and avoid writing to raw ''Context.releases'' property, there is a special high-level API command.


  '''POST''' /implementation?cmd='''release'''[&''PROP''=''VALUE''][&initial]
  '''POST''' /context?cmd='''submit'''[&''PROP''=''VALUE''][&initial]


Where the {{Code|PROP}} arguments are optional Implementation properties to create new resource. The {{Code|initial}} argument asks the system to create new Context resource new Implementation will belong to.
Where the {{Code|PROP}} arguments are optional release properties. The {{Code|initial}} argument asks the system to create new Context resource new release will belong to.


The posting data might be two types,
The posting data might be two types,
Line 168: Line 204:
* Sugar activities in .xo bundles,<br>there is no need in {{Code|PROP}} arguments, all properties will be populated basing on metadata from a .xo bundle; including release notes from the {{Code|CHANGELOG}} file in [[Wikipedia:Markdown|Markdown]] notation; besides, only in this case {{Code|initial}} makes sense because it is the only way to get Context properties;
* Sugar activities in .xo bundles,<br>there is no need in {{Code|PROP}} arguments, all properties will be populated basing on metadata from a .xo bundle; including release notes from the {{Code|CHANGELOG}} file in [[Wikipedia:Markdown|Markdown]] notation; besides, only in this case {{Code|initial}} makes sense because it is the only way to get Context properties;


* Arbitrary data,<br>all required Implementation properties should be specified in {{Code|PROP}} arguments, at least ''context'' and ''version''; ''license'' should be specified only if there are no existing Implementations to pickup license from.
* Arbitrary data,<br>all required release properties should be specified in {{Code|PROP}} arguments, at least ''context'' and ''version''; ''license'' should be specified only if there are no existing releases to pickup license from.


=== Notifications ===
=== Notifications ===
Retrieved from "https://wiki.sugarlabs.org/go/Sugar_Network/API"