On Thursday 10 September 2009, Martin Vidner wrote:
>
> Could you link also the restility source for the studio API, so that
> we know how to write our own docs?
Source is attached.
--
Cornelius Schumacher <[email protected]>
= SUSE Studio User API
Version: v1
SUSE Studio offers a RESTful API which can be accessed entirely via HTTP.
<h3>Changes:</h3>
<ul>
<li>25/08/2009: Added /appliances/<id>/cmd/add_user_repository
call</li>
<li>04/08/2009: Added parameters to set the image type and version when
starting builds</li>
<li>03/08/2009: The API got extended with the following resources and
methods:
<ul>
<li>/user/account</li>
<li>/appliances/<id>/status</li>
<li>/appliances/<id>/repositories</li>
<li>/appliances/<id>/software</li>
<li>/appliances/<id>/cmd</li>
<li>/repositories</li>
</ul>
</li>
<li>02/06/2009: Added /rpms resource for managing uploaded RPMs</li>
</ul>
== Authentication
The Studio API supports two different authentication methods:
<ul>
<li><a href="#http_auth">HTTP Basic authentication</a></li>
<li><a href="#oauth_auth">OAuth authentication</a></li>
</ul>
<h3><a name="http_auth"/></a>HTTP Basic authentication</h3>
The credentials for this authentication method are the username and an API key
as password, which the user can create and change at any time.
<h3><a name="oauth_auth"></a>OAuth authentication</h3>
<b>Note:</b> OAuth authentication has been disabled until the security flaw in
OAuth Core 1.0 has been addressed.
== Table of Contents
Contents
== Account information
GET /user/show_api_key
Returns an HTML page which contains the API key flagged as:<br/><br/>
<tt><span class="studio:api_key">ksdjfu93r</span></tt>.
GET /api/v1/user/account
Returns information about the account, such as username, email address and
disk quota.
XmlResult: account
== Template sets
<name>: Name of template
GET /api/v1/user/template_sets
List all template sets.<br/>
Template sets are used to group available templates by topic. The
<tt>'default'</tt><br/>
template set contains all vanilla SUSE templates, <tt>'mono'</tt> contains
those that<br/>
are optimized to be used for mono applications, for example.
XmlResult: template_sets
GET /api/v1/user/template_sets/<name>
Show template set <tt>name</tt>.
XmlResult: template_set
== Appliances
GET /api/v1/user/appliances
List all appliances of the current user.
XmlResult: appliances
GET /api/v1/user/appliances/<id>
<id>: Id of the appliance
Show details of appliance with id <tt>id</tt>.
XmlResult: appliance
GET /api/v1/user/appliances/<id>/status
<id>: Id of the appliance
Show information on the status of the appliance with id <tt>id</tt>.
XmlResult: appliance_status
POST
/api/v1/user/appliances?<clone_from>=<appliance_id>&<name?>=<name>&<arch?>=<arch>
<clone_from>: The template the new appliance should be based on.
<name>: The name of appliance
<arch>: The architecture of the appliance (x86_64 or i686)
Create a new appliance by cloning a template or another appliance with the id
<tt>appliance_id</tt>.<br/>
If <tt>name</tt> is left out, a name will be generated. If <tt>arch</tt> is
left out a i686 appliance will be created.
DELETE /api/v1/user/appliances/<id>
<id>: Id of the appliance
Delete appliance with id <tt>id</tt>.
=== Repositories
<id>: Id of the appliance
GET /api/v1/user/appliances/<id>/repositories
List all repositories of the appliance with id <tt>id</tt>.
XmlResult: repositories
PUT /api/v1/user/appliances/<id>/repositories
Update the list of repositories of the appliance with id
<tt>id</tt>.<br/><br/>
<strong>Note:</strong> Only the repository ids of the put xml are considered.
XmlResult: repositories
POST /api/v1/user/appliances/<id>/cmd/add_repository?<repo_id>=<repo_id>
<repo_id>: Id of the repository.
Add the specified repository to the appliance with id <tt>id</tt>.
XmlResult: repositories
POST /api/v1/user/appliances/<id>/cmd/remove_repository?<repo_id>=<repo_id>
<repo_id>: Id of the repository.
Remove the specified repository from the appliance with id <tt>id</tt>.
XmlResult: repositories
POST /api/v1/user/appliances/<id>/cmd/add_user_repository
Adds the according user repository (the one containing the uploaded RPMs) to
the appliance.
=== Software Selection
<appliance_id>: Id of the appliance.
<build_id>: Id of the build.
<id>: Id of the appliance
GET /api/v1/user/appliances/<id>/software
List all selected packages and patterns of the appliance with id <tt>id</tt>.
XmlResult: software
PUT /api/v1/user/appliances/<id>/software
Update the list of selected packages and patterns of the appliance with id
<tt>id</tt>.
XmlResult: software
GET /api/v1/user/appliances/<id>/software/installed?<build_id?>=<build>
List all packages and patterns that are installed. You can either specify
the<br/>
appliance with the <tt>appliance_id</tt> parameter, which will list the
software<br/>
that will installed with the next build or via an build id. That makes it
possible<br/>
to retrieve the installed software for older builds.
XmlResult: software_map
POST
/api/v1/user/appliances/<id>/cmd/add_package?<name>=<name>&<version?>=<version>&<repository_id?>=<repo_id>
<name>: Name of the package.
<version>: Version of the package.
<repository_id>: Repository to pick the package from.
Add the specified package to the appliance with id <tt>id</tt>.
XmlResult: software_change
POST /api/v1/user/appliances/<id>/cmd/remove_package?<name>=<name>
<id>: Id of the appliance
<name>: Name of the package.
Remove the specified package from the appliance with id <tt>id</tt>.
XmlResult: software_change
POST
/api/v1/user/appliances/<id>/cmd/add_pattern?<name>=<name>&<version?>=<version>&<repository_id?>=<repo_id>
<id>: Id of the appliance
<name>: Name of the pattern.
<version>: Version of the pattern.
<repository_id>: Repository to pick the pattern from.
Add the specified pattern to the appliance with id <tt>id</tt>.
XmlResult: software_change
POST /api/v1/user/appliances/<id>/cmd/remove_pattern?<name>=<name>
<id>: Id of the appliance
<name>: Name of the pattern.
Remove the specified pattern from the appliance with id <tt>id</tt>.
XmlResult: software_change
GET
/api/v1/user/appliances/<id>/software/search?<q>=<search_string>&<all_fields?>=<all_fields>&<all_repos?>=<all_repos>
<id>: Id of the appliance
<q>: The search string
<all_fields>: Option to perform the search on all fields. Default is 'false'.
<all_repos>: Option to perform the search on all repositories. Default is
'false'.
Search all software that matches the given <tt>search_string</tt>. If the
<tt>all_fields</tt><br/>
parameter is set to <tt>true</tt> all fields are considered, otherwise only
the name of the package<br/>
or pattern is matched against the <tt>search_string</tt>.<br/>
By default only software that is available to the appliance is considered,
e.g. the search is limited to the<br/>
repositories of this appliances. If you want to search in all repositories
set the <tt>all_repos</tt> parameter to <tt>true</tt>.
XmlResult: software_map
=== Image files
<build_id>: Id of the build.
<id>: Id of the appliance.
GET
/api/v1/user/appliances/<id>/image_files?<build_id>=<build_id>&<path>=<path_to_file>
<path>: Path to the file in the built appliance.
Returns the file with the given path from an image.
== Overlay files
<appliance_id>: Id of the appliance.
<file_id>: Id of the file.
GET /api/v1/user/files?<appliance_id>=<id>
List all overlay files of appliance with id <tt>id</tt>.
XmlResult: files
POST
/api/v1/user/files?<appliance_id>=<id>&<filename?>=<name>&<path?>=<path>&<owner?>=<owner>&<group?>=<group>&<permissions?>=<perms>&<enabled?>=<enabled>
<filename>: The name of the file in the filesystem.
<path>: The path where the file will be stored.
<owner>: The owner of the file.
<group>: The group of the file.
<permissions>: The permissions of the file.
<enabled>: Used to enable/disable this file for the builds.
Adds a file to the appliance with id <tt>id</tt>.<br/>
Optionally, one or more metadata settings can be specified. If those are left
out, they<br/>
can also be change later (see below).<br/>
The file is expected to be wrapped as with form-based file uploads in HTML
(RFC 1867) in the body of the POST request.
XmlResult: file
GET /api/v1/user/files/<file_id>/data
Returns the file with id <tt>file_id</tt>.
PUT /api/v1/user/files/<file_id>/data
Writes the content of the file with id <tt>file_id</tt>.<br/>
The file is expected to be wrapped as with form-based file uploads in HTML
(RFC 1867) in the body of the PUT request.
XmlResult: file
GET /api/v1/user/files/<file_id>
Returns the meta data of the file with id <tt>file_id</tt>.
XmlResult: file
PUT /api/v1/user/files/<file_id>
Writes the meta data of the file with id <tt>file_id</tt>.
XmlResult: file
DELETE /api/v1/user/files/<file_id>
Delete the file with id <tt>file_id</tt> and its meta data.
== Running builds
<appliance_id>: Id of the appliance.
<build_id>: Id of the build.
GET /api/v1/user/running_builds?<appliance_id>=<id>
List all running builds for the appliance with id <tt>id</tt>.
XmlResult: running_builds
GET /api/v1/user/running_builds/<build_id>
Show status of the build with id <tt>build_id</tt>.
XmlResult: running_build
POST
/api/v1/user/running_builds?<appliance_id>=<id>&<force?>=<force>&<version?>=<version>&<image_type?>=<type>
<force>: Force a build even if it overwrites an already existing build.
<version>: The version of the appliance.
<image_type>: The format of the build. Supported are 'xen','oem','vmx' and
'iso'.
Start a new build for the appliance with id <tt>id</tt>.<br/>
If there already is a build with the same appliance settings (build type and
version)<br/>
an error is returned. In this case a build can be enforced by setting the
optional<br/>
<tt>force</tt> parameter to <tt>true</tt>.<br/>
Optionally the appliance version and build type can be set with the
<tt>version</tt> and <tt>image_type</tt>
parameters.
DELETE /api/v1/user/running_builds/<build_id>
Cancel build with id <tt>build_id</tt>.
== Finished builds
<appliance_id>: Id of the appliance.
<build_id>: Id of the build.
GET /api/v1/user/builds?<appliance_id>=<id>
List all completed builds for the appliance with id <tt>id</tt>.
XmlResult: builds
GET /api/v1/user/builds/<build_id>
Show build info of the build with id <tt>build_id</tt>.
XmlResult: build
DELETE /api/v1/user/builds/<build_id>
Delete build with id <tt>build_id</tt>.
== RPM Uploads
<base_system>: Base system of the RPM or archive, e.g. 11.1 or SLED11.
<rpm_id>: ID of the uploaded RPM.
GET /api/v1/user/rpms?<base_system>=<base>
List all uploaded RPMs for the base system <tt>base</tt>.
XmlResult: rpms
GET /api/v1/user/rpms/<rpm_id>
Show information on the uploaded RPM with id <tt>rpm_id</tt>.
XmlResult: rpm
GET /api/v1/user/rpms/<rpm_id>/data
Returns the RPM with id <tt>rpm_id</tt>.
POST /api/v1/user/rpms?<base_system>=<base>
Adds an RPM or archive to the user repository for appliances base on
<tt>base</tt>.<br/>
The file is expected to be wrapped as with form-based file uploads in HTML
(RFC 1867) in the body of the POST request.
XmlResult: rpm
PUT /api/v1/user/rpms/<rpm_id>
Update the content of the RPM or archive with the id <tt>rpm_id</tt>.<br/>
The file is expected to be wrapped as with form-based file uploads in HTML
(RFC 1867) in the body of the POST request.
XmlResult: rpm
DELETE /api/v1/user/rpms/<rpm_id>
Deletes the RPM or archive with the id <tt>rpm_id</tt> from the user
repository.
== Repositories
GET /api/v1/user/repositories?<base_system?>=<base>&<filter?>=<search_string>
<base_system>: Limit the results to repositories with this base system.
<filter>: Only show repositories matching this search string.
Returns a list of repositories. If neither <tt>base_system</tt> nor
<tt>filter</tt> are
specified all available repositories are returned.<br/>
When filtering the results with the <tt>filter</tt> parameter, the repository
name,
repository url and repository packages are searched.
XmlResult: repositories
POST /api/v1/user/repositories?<url>=<url>&<name>=<name>
<url>: Base url of the repository.
<name>: Name for the repository.
Imports a new repository into Studio. Returns the metadata for the created
repository.
XmlResult: repository
GET /api/v1/user/repositories/<id>
<id>: Id of the repository.
Show information on the repository with the id <tt>id</tt>.
XmlResult: repository
