Skip to content

ConductorAPIv1_0

Jump to bottom Edit New page
Mo Morsi edited this page Jan 11, 2013 · 2 revisions

Conductor API

Conductor Exposes a limited API for controlling a subset of conductor API resources. This subset is currently based around Image manipulation. This guide shows how to create requests and what the responses should look like.

N.B. All examples in this document presume conductor is setup using the default url “https://localhost/conductor”

Request Headers

Conductor API currently only supports requests in XML format. All requests should have the content-type and Accept headers set to application/xml

Listing Collections

To list a resource collection a GET request must be sent to <conductor_url>/api/<plural_of_resource_name>

Listing Images

curl --user admin:password--header “Accept: application/xml” https://localhost/conductor/api/images -k ( -k in this case tells curl to ignore SSL)

<images>
  <image href='https://localhost/conductor/api/images/aad95492-e165-43fa-b8d0-af184a21ca9f' id='aad95492-e165-43fa-b8d0-af184a21ca9f'>
   <name>tmpl1</name>
   <description>foo</description>
   <os>Fedora</os>
   <os_version>14</os_version>
   <arch>x86\_64</arch>
   <builds type='xs:list'>
     <build href='https://localhost/conductor/api/builds/5ee69b07-019d-413d-b74f-cf65defcc64b' id='5ee69b07-019d-413d-b74f-cf65defcc64b'></build>
   </builds>
  </image>
</images>

Listing Builds

curl --user admin:password--header “Accept: application/xml” https://localhost/conductor/api/builds -k ( -k in this case tells curl to ignore SSL)

<builds>
  <build href='https://localhost/conductor/api/builds/5ee69b07-019d-413d-b74f-cf65defcc64b' id='5ee69b07-019d-413d-b74f-cf65defcc64b'>
    <image href='https://localhost/conductor/api/images/aad95492-e165-43fa-b8d0-af184a21ca9f' type='xs:string'>aad95492-e165-43fa-b8d0-af184a21ca9f</image>
  </build>
</builds>

Listing Target Images

curl --user admin:password--header “Accept: application/xml” https://localhost/conductor/api/target_images -k

( -k in this case tells curl to ignore SSL)

<target_images>
  <target_image href='https://localhost/conductor/api/target_images/8248e4f4-311a-419d-8867-bf3dcb38d48b' id='8248e4f4-311a-419d-8867-bf3dcb38d48b'>
   <object_type>target\_image</object_type>
   <template>78ac256c-a085-4199-92cf-1aa3e44c66e8</template>
   <build href='https://localhost/conductor/api/builds/5ee69b07-019d-413d-b74f-cf65defcc64b' id='5ee69b07-019d-413d-b74f-cf65defcc64b'></build>
   <status>COMPLETE</status>
   <provider_images>
   </provider_images>
  </target_image>
</target_images>

Listing Provider Images

curl --user admin:password--header “Accept: application/xml” https://localhost/conductor/api/provider_images -k

( -k in this case tells curl to ignore SSL)

<provider_images>
  <provider_image href='https://localhost/conductor/api/provider_images/669bcd8d-7b01-4ec6-80e1-c77c188692ba' id='669bcd8d-7b01-4ec6-80e1-c77c188692ba'>
   <object_type>provider\_image</object_type>
   <target_identifier>ami</target_identifier>
   <status>COMPLETE</status>
   <provider>ec2-us-east-1</provider>
     <target_image href='https://localhost/conductor/api/target_images/3db70983-f9e9-419b-8f92-782c90ba55af' id='3db70983-f9e9-419b-8f92-782c90ba55af'></target_image>
  </provider_image>

  <provider_image href='https://localhost/conductor/api/provider_images/eb13a83c-ce7b-4070-8c48-ce952e8936eb' id='eb13a83c-ce7b-4070-8c48-ce952e8936eb'>
   <object_type>provider\_image</object_type>
   <target_identifier>ami</target_identifier>
   <status>COMPLETE</status>
   <provider>ec2-us-east-1</provider>
     <target_image href='https://localhost/conductor/api/target_images/be9092ce-9143-451c-a45c-b44cd1fa71e9' id='be9092ce-9143-451c-a45c-b44cd1fa71e9'></target_image>
  </provider_image>
</provider_images>

Listing Target Images

curl --user admin:password--header “Accept: application/xml” https://localhost/conductor/api/target_images -k

( -k in this case tells curl to ignore SSL)

Showing Resources

In order to only hold of a resource a GET request should be sent to the collection_url/<resource_id>

Show Image Example

curl --user admin:password--header “Accept: application/xml” https://localhost/conductor/api/images/aad95492-e165-43fa-b8d0-af184a21ca9f -k

<image href='https://localhost/conductor/api/images/aad95492-e165-43fa-b8d0-af184a21ca9f' id='aad95492-e165-43fa-b8d0-af184a21ca9f'>
  <name>tmpl1</name>
  <description>foo</description>
  <os>Fedora</os>
  <os_version>14</os_version>
  <arch>x86_64</arch>
  <builds type='xs:list'>
    <build href='https://localhost/conductor/api/builds/5ee69b07-019d-413d-b74f-cf65defcc64b' id='5ee69b07-019d-413d-b74f-cf65defcc64b'></build>
  </builds>
</image>

Creating new Resources

Conductor API only allows the creation of Images, Builds, Target Images, Provider Images.

Creating a new Image with a single Target

In order to create a Target Image with a new Build and Image, a POST request should be sent the images collection url. This post request must* a targets and also an XML template.

curl -X POST--user admin:password--header “Accept: application/xml” --data “ec2$TEMPLATE” https://localhost/conductor/api/images -k

<image href='https://localhost/conductor/api/images/fd1f7cbd-8246-4e9d-b7a8-2b79731334bd' id='fd1f7cbd-8246-4e9d-b7a8-2b79731334bd'>
  <build href='https://localhost/conductor/api/builds/81cb0332-3dc9-4846-8fdf-138cfc8790ec' id='81cb0332-3dc9-4846-8fdf-138cfc8790ec'>
    <target_images>
      <target_image href='https://localhost/conductor/api/target_images/a6cf95c7-e9b2-4e5b-9c12-4a39f8356c4b' id='a6cf95c7-e9b2-4e5b-9c12-4a39f8356c4b'>
      <status>New</status>
      <provider_images>
      </provider_images>
      </target_image>
    </target_images>
  </build>
</image>

Creating a new Image for multiple Targets

In order to create a new images with a Target Image for a number of different providers, a POST request should be sent the images collection url. This post request must* contain a comma separated list of targets and also an XML template.

curl -X POST--user admin:password--header “Accept: application/xml” --data “ec2,mock$TEMPLATE” https://localhost/conductor/api/images -k

<image href='https://localhost/conductor/api/images/444abbb3-e89e-4ce8-9800-b0ae86416112' id='444abbb3-e89e-4ce8-9800-b0ae86416112'>
  <build href='https://localhost/conductor/api/builds/f1b4a041-a6b9-4e18-bc61-1e389f4a262f' id='f1b4a041-a6b9-4e18-bc61-1e389f4a262f'>
    <target_images>
      <target_image href='https://localhost/conductor/api/target_images/3536c69c-f326-4b59-9879-ee1e3b08e458' id='3536c69c-f326-4b59-9879-ee1e3b08e458'>
        <status>New</status>
        <provider_images>
        </provider_images>
      </target_image>
      <target_image href='https://localhost/conductor/api/target_images/4330d17f-d842-4512-8c78-bb65c970cbb5' id='4330d17f-d842-4512-8c78-bb65c970cbb5'>
        <status>COMPLETED</status>
        <provider_images>
        </provider_images>
      </target_image>
    </target_images>
  </build>
</image>

Pushing Images to Providers

Once you have created an image with particular target images, you can then push them to a particular provider. This will upload the image to the cloud provider and return a provider image which represents the uploaded images. Pushing an image can be achieved by create a new Provider Image resource. This can be achieve by creating a post request to the provider images url. The request body must specify a list of accounts, (for which the target images will be pushed to) and either a Target Image, Build or Image.

Pushing a specific Target Image

Pushing a specific target image can be achieved by adding a target image parameter to the XML request body and a provider account.

curl -X POST--user admin:password--header “Accept: application/xml” --data “<provider_image><target_image_id>c118d12b-a4a2-4217-88cb-48cc06f6e5b5</target_image_id><provider_account>ec2-acc</provider_account></provider_image>” https://localhost/conductor/api/provider_images -k

<provider_images>
  <provider_image href='https://localhost/conductor/api/provider_images/019e7f0d-e4f4-47c5-8b91-adf4561a61e6' id='019e7f0d-e4f4-47c5-8b91-adf4561a61e6'>
    <status>New</status>
  </provider_image>
</provider_images>

Pushing a Build (Multiple Push)

Pushing a build will push all the target images associated with the build. This allows consumers of the API to push multiple target images with one command. To push a build, the build_id and a comma separated list of provider accounts must be supplied. Target Images will be pushed to all the accounts specified, provider there is a target image for the specific target i.e. the provider type of the account.

curl -X POST--user admin:password--header “Accept: application/xml” --data “<provider_image><build_id>82b28e06-64dd-4081-a8db-82c9477f53f6</build_id><provider_account>ec2-acc,mock-acc</provider_account></provider_image>” https://localhost/conductor/api/provider_images -k

<provider_images>
  <provider_image href='https://localhost/conductor/api/provider_images/2593319c-930c-4d18-a277-8575c15714d7' id='2593319c-930c-4d18-a277-8575c15714d7'>
    <status>New</status>
  </provider_image>

  <provider_image href='https://localhost/conductor/api/provider_images/1de0cddd-06eb-46f1-bd3d-5dfd69f44e0b' id='1de0cddd-06eb-46f1-bd3d-5dfd69f44e0b'>
    <status>PENDING</status>
  </provider_image>
</provider_images>

Pushing an Image (Multiple Push)

Pushing an Image behaves in the same way as pushing a Build, only we specify image id in the request. This feature is not yet fully utilized since we currently do not support multiples builds per image, however this is a possibility in the future.

curl -X POST--user admin:password--header “Accept: application/xml” --data “<provider_image><image_id>67533740-83c3-4a3b-a69b-7b69634e4791</image_id><provider_account>ec2-acc,mock-acc</provider_account></provider_image>” https://localhost/conductor/api/provider_images -k

<provider_images>
  <provider_image href='https://localhost/conductor/api/provider_images/5ee6c899-0ddc-4b0c-a007-e1296f4180b8' id='5ee6c899-0ddc-4b0c-a007-e1296f4180b8'>
    <status>New</status>
  </provider_image>

  <provider_image href='https://localhost/conductor/api/provider_images/3611b344-f862-49f3-98d8-23e67bf8ba02' id='3611b344-f862-49f3-98d8-23e67bf8ba02'>
    <status>COMPLETED</status>
  </provider_image>
</provider_images>

Error Codes

  • BuildDeleteFailure : An error occured when deleting the Build from the Image Warehouse
  • BuildNotFound : Could not find the specified Build
  • ImageDeleteFailure : An error occured when deleting the Image from the Image Warehouse
  • ImageNotFound : Could not find the specified Image
  • InsufficientParametersSupplied : There were insufficient parameters provided in the request
  • ParameterDataIncorrect : The given parameters are incorrect
  • PushError : An error occured the Image Factory when trying to push
  • ProviderAccountNotFound : Could not find the specified account
  • ProviderImageDeleteFailure : An error occurd when deleting the Provider Image from Image Warehouse
  • ProviderImageNotFound : Could not find the specified Provider Image
  • ProviderImageStatusNotFound : There was no status supplied in the Provider Image
  • TargetImageDeleteFailure : An error occured when deleting the Target Image from the Image Warehouse
  • TargetImageNotFound : Could not locate the specified Target Image
  • TargetImageStatusNotFound : There was no status supplied in the Target Image
  • TargetNotFound : Could not locate the specified Target
Add a custom footer
Add a custom sidebar
Clone this wiki locally