RFC: Deployable, Deployment, and Instance API

Scott Seago sseago at redhat.com
Fri Jul 20 16:29:27 UTC 2012


On 07/20/2012 11:31 AM, Jason Guiditta wrote:
> On 19/07/12 13:51 -0400, Scott Seago wrote:
>> On 07/17/2012 03:13 PM, Richard Su wrote:
>>> Hi,
>>>
>>> Below is an outline of REST API endpoints that we would need to 
>>> implement to allow users to automate further their interactions with 
>>> Conductor. The endpoints follows the actions available in the 
>>> current Conductor UI flow.
>>>
>>> The contents is also up this wiki page 
>>> https://www.aeolusproject.org/redmine/projects/aeolus/wiki/Deployable_Deployment_and_Instance_API
>>>
>>>
>>> Endpoints
>>>
>>> conductor/api/deployables
>> Is it safe to assume that all of the API will also work on the 
>> standard controller action URLs (i.e. /conductor/deployables, etc)? 
>> If we're doing this as planned, using the same controller actions 
>> that we use for the UI, then in most cases /conductor/api/foo will 
>> just be a route that returns /conductor/foo. The regular actions will 
>> do the normal UI html generation in the html render block, and the 
>> API rendering in the xml and json blocks
>
> Yes, I have been advocating this as well, the api (and potentially
> api/v#) would just be conveniance/alias routes to the same controller
> the UI uses.
>
>>> 1. Create given name, catalog id(s), and deployable xml.
>>>   Deployable xml is validated before it can be saved.
>>>   Reference for Deployable XMLs - 
>>> https://www.aeolusproject.org/redmine/projects/aeolus/wiki/Deployable_XML
>>> 2. Show a deployable
>>> 3. Index of deployables - list name and href to id
>> This takes an optional catalog_id -- i.e. either list deployables in 
>> a catalog, or list all deployables (filtered by permission of 
>> course). That part is already in the controller logic, though.
>>> 4. Delete a deployable
>>> 5. Edit a deployable
>>>   PUT new deployable xml, respond with 200 and newly saved object
>>>   Allow update of name and catalog ids
>>>
>>> The images defined in the deployable xml must exist, but they need 
>>> not be built or pushed. If there are multiple assemblies, any 
>>> missing image should fail the validation.
>>>
>>> conductor/api/deployments
>> And this should also work under /conductor/deployments since the 
>> controller is there anyway. Same comment applies to the other object 
>> types below as well.
>
> +1
>
>>> 1. Create given name, deployable id, and optional realm
>>>   All images defined in the deployable must be built and pushed to 
>>> the choosen realm
>>>   Launches instances
>> Don't forget pool -- that's required -- you'll see that when you add 
>> the api stuff to the existing controller action.
>>
>>> 2. Show a deployment and its instances
>>>   Each instance is listed with name and a link to the real object
>>> 3. Index of deployments
>>> 4. Delete a deployment
>>> 5. Edit a deployment - not available
>>>
>> What about other deployment actions? 'stop', 'start' (once we can 
>> re-start stopped ones), 'reboot', etc.
>
> My thought on this was that they should all just be treated as
> updates, iow, PUT the desired changes/fields in the request to
> initiate the desired action.  Having a separate methods doesnt feel
> like it fits into REST properly to me. If there is disagreement here,
> I think this is a good place to iron it out, as the pattern needs to
> be established and made consistent now, before things get even more
> complex (like adding other layers of api, etc).
>
Hmm. The thing is it's not really an update. To 'stop' an instance isn't 
an update to the 'state' -- the state won't change until the action is 
done. We're explicitly requesting that an action occur on an instance 
("please stop this now", "please start this tomorrow morning"), which, 
REST or not, doesn't feel like an update -- it's a request to do 
something that might (eventually) result in an update. Surely there's a 
REST-appropriate way of doing this that doesn' obscure the fact that 
it's not really an update.

Scott

>>> conductor/api/deployments/$id/instances
>>> conductor/api/instances
>>> 1. Stop an instance
>>> 2. Start an instance
>>> 3. List all instances for a given deployment
>>> 4. List all instances I can control across all deployments - TBD
>>> 5. Show instance, status, ip address, ssh keys, etc..
>>>
>>> conductor/api/realms
>>> 1. Create, map to provider, map to provider realm
>>> 2. Show a realm
>>> 3. List all realms
>>> 4. Delete a realm
>>> 5. Edit a realm and mappings
>>>
>>> conductor/api/provider_accounts/$id/realms
>>> 1. List from provider accounts
>>>
>>> conductor/api/hardware_profiles/
>>> CRUD
>>>
>>> conductor/api/catalogs
>>> CRUD
>>>
>>> conductor/api/pools
>>> CRUD, catalogs are mapped to a pool
>>>
>>> ---
>>> Reference
>>>
>>> Initial planning discussion - 
>>> http://etherpad-aeolusproject.rhcloud.com/p/deployables_and_instance_api 
>>>
>>>
>>




More information about the aeolus-devel mailing list