incubator-deltacloud-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Lutterkort <lut...@redhat.com>
Subject Re: [PATCH] REST API update - WORK IN PROGRESS DO NOT COMMIT
Date Tue, 19 Jul 2011 00:02:55 GMT
On Fri, 2011-07-15 at 18:56 +0300, marios@redhat.com wrote:
> From: marios <marios@redhat.com>

This is great - I really like where this is going.

A have a few nitpicky/editorial comments:

First nitpick: please keep lines to 80 chars or less; there's a ton of
very long lines ...

> +## 1. Introduction
> +
> +Apache Deltacloud is a REST-based (HATEOAS) cloud abstraction API,
> that enables management of resources in different IaaS clouds using a
> single API. A series of back-end drivers 'speak' each cloud provider's
> native API and the Deltacloud Core Framework provides the basis for
> implementing drivers as needed for other/new IaaS cloud providers.
> Apache Deltacloud currently supports: Amazon EC3 and S3, Rackspace
> Cloud Servers and Cloud Files, Gogrid Cloud Servers, Terremark Vcloud
> Express, Rimuhosting VPS, Red Hat Enterprise Virtualisation (rhev-m),
> Microsoft Azure (currently Blob storage only), Opennebula, Eucalyptus
> (including Walrus storage service), IBM Smart Business Cloud and
> VMware vSphere.

Instead of enumerating all the supported backends, just include a link
to http://localhost:4331/drivers.html#h4 - there's a higher likelihood
that we'll keep that page up to date.

> +### 1.3 Authentication
> +
> +The Deltacloud API server is stateless, and does not keep any information
> +about the current client. In particular, it does not store the credentials for
> +the backend cloud it is talking to. Instead, it uses HTTP basic authentication,
> +and clients have to send the username/password for the backend cloud on every request.
> +
> +The specifics of what needs to be sent varies from cloud to cloud; some
> +cloud providers employ a username and password for API access, whilst
> +others use special-purpose API keys.

Include a link to http://localhost:4331/documentation.html where we list
what the actual creds are for every cloud.

> +### 1.6 API stability and evolution
> +
> +Future changes to the API will be made in a manner that allows old clients
> +to work against newer versions of the the API server.

We should explain what we mean by API stability. Maybe something like
the following:

        The stability guarantees given by the API imply that the
        following changes may happen in newer versions of the API:
        
              * adding new collections, or supporting new operations on
                existing collections
              * adding optional parameters to existing operations
              * adding additional attributes and elements to the XML
                responses
        
        On the other hand, these changes would violate API stability,
        and will therefore not be made
        
              * removing an operation on a collection
              * making an optional parameter for an operation mandatory
              * removing attributes or elements from XML responses

> +### 2.1 Features
> +
> +The Apache Deltacloud API defines the standard behavior and semantics
> +for each of the resource types as a baseline for any API implementation; it
> +is often desirable to enhance standard API behavior with specific features.
> +The API also defines all the features that can be supported by an API
> +implementation - each of them has a fixed, predefined meaning. As an
> +example, the feature user-name indicates that a user-specified name can be
> +assigned to an instance when it is created. Features are advertised in the
> +top-level entry point as illustrated below:

We should include a list of all the features (maybe in an appendix, or
right here) and then have individual operations list what features may
apply to them.

The important thing about the list of features is to explain what each
of them means, in particular 'if you see feature hamncheese, you know
that the create instance operation can also make you a ham and cheese
sandwich'

David



Mime
View raw message