Mailinglist Archive: yast-devel (163 mails)

< Previous Next >
Re: [yast-devel] WebYast: Documenting REST API - findings
  • From: Cornelius Schumacher <cschum@xxxxxxx>
  • Date: Thu, 10 Sep 2009 19:03:19 +0200
  • Message-id: <200909101903.20040.cschum@xxxxxxx>
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 <cschum@xxxxxxx>
= 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/&lt;id&gt;/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/&lt;id&gt;/status</li>
<li>/appliances/&lt;id&gt;/repositories</li>
<li>/appliances/&lt;id&gt;/software</li>
<li>/appliances/&lt;id&gt;/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>&lt;span class="studio:api_key"&gt;ksdjfu93r&lt;/span&gt;</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
< Previous Next >