Open main menu

Sugar Labs β


Sugar Network/API

1,019 bytes added, 23:34, 17 March 2014
Sugar Network resources
== Nodes ==
This is an API provided by Sugar Network nodes.
=== Authentication ===
* raw data or redirection for BLOB properties.
=== Aggregated properties === [[Sugar_Network/Resources#Property_types|Aggregated]] properties have special API to treat their content. <div id="HEADPOST-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 The resulting info is a Sugar Activity bundle from the Sugar Network, it is required JSON object with keys equal to find out the GUID of ''Implementation'' Context guids and value objects for chosen release 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).following keys:
'''GET''' * {{Code|blob}}, bundle [[Sugar_Network/context/''GUID''?cmd='''clone'''[&requires=''DEPENDENCY''Resources#Property_types|digest][&''PROP''=''VALUE'']to download; * {{Code|version}}, chosen version number;* {{Code|title}}, the ''Context.title'HEAD''' /context/''GUID''?cmd='''clone'''[&requires=''DEPENDENCY''][&''PROP''=''VALUE'']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 '''GET''' /context/Resources|Implementation]] property values, such as ''stabilityGUID'' or ?cmd=''version'clone', to filter implementations by. The ''[&requires=''DEPENDENCY'' parameter has a special meaning, it is intended to select an implementation by its ][[Sugar_Network/Recipe_Specification#requires|dependency list]&lsb_id=''LSB_ID'']. {{Code|DEPENDENCY}} value is multiple and should conform Sugar Network [[Sugar_Network/Recipe_Specification#Dependencies|recipe specification]&lsb_release=''LSB_RELEASE''].
The {{Code|'''HEAD'''}} command will not return bundle itself but rather its Like the [[#HEADGET-propertysolve|metadatasolve]] combined with selected command, ''Implementationclone'' propertiesmakes a solution but returns bundle itself, i.e., it ignores possible dependencies.
=== Upload new releases ===
The regular procedure to To easy upload new Implementation objects is using the {{CodeContext [[Sugar_Network/Resources#context-releases|POST /implementation}} API command with specifying new Implementation properties releases]] and {{Code|PUT}}avoid writing to raw ''ing new bundle itselfContext. To make this process shorterreleases'' property, there is a special high-level API command.
'''POST''' /implementationcontext?cmd='''releasesubmit'''[&''PROP''=''VALUE''][&initial]
Where the {{Code|PROP}} arguments are optional Implementation release properties to create new resource. The {{Code|initial}} argument asks the system to create new Context resource new Implementation release will belong to.
The posting data might be two types,
* 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 release properties should be specified in {{Code|PROP}} arguments, at least ''context'' and ''version''; ''license'' should be specified only if there are no existing Implementations releases to pickup license from.
=== Notifications ===