Conductor_Image_Management_API_design

Conductor Image Management API

In order to allow third party clients such as aeolus-image and Katello access the Image management functionality of Aeolus we shall expose an appropriate Image management API on top of conductor. This document outlines a design of a Restful API. The first draft will expose the functionality needed for aeolus-image only. Future design will incorporate changes needed for Katello integration.

This document is largely based on the guide written by Geert Jansen found here: http://readthedocs.org/docs/restful-api-design/en/latest/

Data Structure

Conductor already exposes a REST API for particular resources. These resources are represented as XML documents, so we shall continue to use XML for the data model. We shall stick to the following rules, in order to maintain consistency and compatibility with ActiveResource:

• Resources are mapped to XML elements with a tag name equal to the resource type.
• Attributes of resources are mapped to XML child elements with the tag name equal to the attribute name.
• Scalar values are stored as text nodes. A special “type” attribute on the containing element should be used to refer to an XML Schema Part 2 type definition.
• Lists should be stored as a single container element with child elements for each list item. The tag of the container element should be the English plural of the attribute name. The item tag should be the English singular of the attribute name. Lists should have the “xd:list” type annotation.
• id and href attributes shall exist on all resources on the root element, where the id is the unique identifier of the resource and the href is an absolute URL pointing to the resource.
• Relationships should be included in the resource, and should be in the form resource type, including id and href only. For many relations include a collection, with only root level elements.

Example

<image id='12341234'  href='http://localhost/conductor/images/12341234>
 <name>MyImage</name>
 <description>This is a description for MyImage</description>
 <os>Fedora</os>
 <os_version>15</os_version>
 <arch>x86\_64</arch>
</image>

<builds>
  <build id='56785678' href='http://localhost/conductor/builds/56785678'/>
  <build id='56785678' href='http://localhost/conductor/builds/56785678'/>
</builds>

URL Structure

We shall stick to the guides outlined in Geerts document: http://readthedocs.org/docs/restful-api-design/en/latest/urls.html

Each collection and resource in the API has its own URL. URLs should never be constructed by an API user. Instead, the user should only follow links that are generated by the API itself. The recommended convention for URLs is to use alternate collection / resource path segments, relative to the API entry point. This is best described by example. The table below uses the ”:name” URL variable style from Rail’s “Routes” implementation.

• /api - The API entry point
• /api/:coll - A top-level collection named “coll”
• /api/:coll/:id - The resource “id” inside collection “coll”
• /api/:coll/:id/:subcoll - Sub-collection “subcoll” under resource “id2”
• /api/:coll/:id/:subcoll/:subid - The resource “id2” inside “subcoll”

We will only allow a maximum of 2 levels of collections at any point. This means that we will not have sub-collections of sub-collections listed in any resource.

For example, An Image may have many builds which may in turn have many target images. When listing the image, we only show builds, target images are in the next level down, and are accessible by looking at the Build resource which contains them.

Resources

The initial design will expose all the resources needed to maintain the aeolus-image CLI functionality. This includes directly exposing the objects handled by Image Factory and Image Warehouse, as well as a subset of objects managed by conductor.

Image Warehouse & Image Factory

• Images
• Builds
• TargetImages
• ProviderImages These resources will offer full CRUD functionality through the API.

Conductor

• Providers
• Provider Accounts
• Targets (Provider Types) These resources will be Read only. Any attempt to Create, Update or Delete any of these resources will result in a 401 Unauthorized response.

Resource Methods

We shall use the standard HTTP methods for CRUD operations on resources.

• GET - Retrieve a collection/resource
• POST - Create a new resource
• PUT - Update a resource
• DELETE - Delete a resource

When Creating or Updating a resource, the created/updated resource shall be returned in the response body as well as setting a 200 - OK repsonse.

Building/Pushing Images

We will follow suit with ImageFactory REST API

Conductor Controllers

Requests for conductor objects such as providers, provider accounts and targets shall remain as they currently are in conductor.

Extra controllers will be needed in order to fulfil requests to manipulate Image Warehouse/Factory resources. These requests shall be handled “statelessly” in conductor. Conductor will simply wrap requests to Image Factory/Warehouse and transform the responses into the relevant XML. (Conductor will use the aeolus-image-rubygem for all communication between itself and Image Factory/Warehouse).

Authentication

Conductor will use HTTP Basic Authentication for API requests (as it already does). It will also need to support 2-Legged OAuth once we integrate with Katello, but that is out of the scope of this document.