← Back to team overview

openstack team mailing list archive

Re: API Spec

 

I'm a huge fan of Peter Coad in the area of software architecture.
One of the largest hurdles to overcome is the separation between code
& design.  The larger the gap, the more they diverge and the greater
the inconsistencies become.  Many tools (like xdoclet, Together, etc.)
have focused on keeping the code and design better in sync.  There are
some projects that do a very good job of having core documentation in
the code (Cocoon) and others that have had it much more separated
(Jini / River). The one thing that I have seen more common in having
far separated design docs, is that most current ones have reference
systems that are taken as the correct implementation and still
override the docs.

As we don't have a "reference implementation" to point to, I think
keeping the core spec in the code is better, but it will require more
adherence to a design pattern that can pull quality documentation from
the code base.  Leveling that documentation is hard though, but seems
to be quite worth it.

Thor HW

On Sat, Aug 27, 2011 at 6:44 PM, George Reese
<george.reese@xxxxxxxxxxxxx> wrote:
> I don't necessarily agree with that approach. I'm not sure if that's the way
> AWS does things or not, but you will note that the AWS APIs are very
> fragmented across projects.
> I think there are several principles that may at times be in conflict that
> need to be in place:
> * Any GA feature should be exposed via API at the time of its GA-ness.
> * There needs to be a "gatekeeper" (possibly the wrong word) ensuring that
> the APIs are self-consistent
>
>
> And the understanding should exist that modeling something for functionality
> may not be the same as the way it is modeled in the API. In fact, the
> underlying model will likely be refactored many times by the API must be
> timeless (but evolvable).
> -George
> On Aug 28, 2011, at 2:29 AM, Jonathan Bryce wrote:
>
> This is on the agenda for Tuesday's policy board meeting (in
> #openstack-meeting 1 hour before the weekly OpenStack team meeting for those
> interested). Sounds like a potentially acceptable solution is to set some
> cross-project API standards and then push the remainder of the API
> definition and implementation into each project. Then the API can progress
> with the underlying project's features as the developers see fit.
> Jonathan.
>
> On Aug 27, 2011, at 4:16 PM, Tim Bell wrote:
>
> I have an api, diablo nova v1.1.
>
> What we are talking about is if it covers 100% functionality.
>
> I can start my deployment testing with v1.1.  The limiting factor is not
> v1.1 vs v1.x for most sites. It is packaging, user exits and integration,
> not whether feature X is in the latest API.
>
> Tim.
>
> ----- Reply message -----
> From: "George Reese" <george.reese@xxxxxxxxxxxxx>
> To: "Tim Bell" <Tim.Bell@xxxxxxx>
> Cc: "openstack@xxxxxxxxxxxxxxxxxxx" <openstack@xxxxxxxxxxxxxxxxxxx>
> Subject: [Openstack] API Spec
> Date: Sat, Aug 27, 2011 20:47
>
>
>
> A cloud platform simply isn't functional without an API. It is a core
> requirement.
>
> No API, no cloud.
>
> -George
>
> On Aug 27, 2011, at 7:04 PM, Tim Bell wrote:
>
>> I'm also a non-API expert but getting a stable open cloud engine with a
>> reasonable API would seem to be a good target before we look to enhance it.
>>
>> There are lots of potential users of Nova (including Rackspace) who would
>> like to get Nova into production.  An API will fully exploits all of the
>> underlying functionality should be discussed/planned in the longer term but
>> let's get Diablo out and deployable first.
>>
>> Tim Bell
>> CERN
>>
>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~openstack
>> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~openstack
>> More help   : https://help.launchpad.net/ListHelp
>
> --
> George Reese - Chief Technology Officer, enStratus
> e: george.reese@xxxxxxxxxxxxx    t: @GeorgeReese    p: +1.207.956.0217    f:
> +1.612.338.5041
> enStratus: Governance for Public, Private, and Hybrid Clouds - @enStratus
> - http://www.enstratus.com
> To schedule a meeting with me: http://tungle.me/GeorgeReese
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
>
> --
> George Reese - Chief Technology Officer, enStratus
> e: george.reese@xxxxxxxxxxxxx    t: @GeorgeReese    p: +1.207.956.0217    f:
> +1.612.338.5041
> enStratus: Governance for Public, Private, and Hybrid Clouds - @enStratus
> - http://www.enstratus.com
> To schedule a meeting with me: http://tungle.me/GeorgeReese
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
>
>


Follow ups

References