On Fri, 2010-12-17 at 10:06 -0500, Toby Crawley wrote:
> > This is the first release of Deltacloud as part of the Apache Incubator.
> > With this release, the Deltacloud API can also be considered stable -
> > any changes to the API in future releases will be done in such a way
> > that existing clients will work with a newer server, i.e. API changes
> > will be fully backwards-compatible.
> >
>
> I think this may need a little clarification.
You are absolutely right - we need to specify this in more detail.
> What constitutes the API? Is it the structure and XML defined in [1],
> or does it include other items as well (response codes, specific
> collection/resource xml, etc)?
>
> And what constitutes a client? Is it required to parse and respect the
> HATEOS links in /api and further down, or will 'clients' that hardcode
> collection paths and ignore /api be considered clients under this
> constraint?
Here's what I understand under API stability:
* as for the structure of the XML, clients need to be prepared for
the fact that additional elements and attributes may be added to
the XML; the nesting and meaning of existing entries will remain
fixed
* response codes are fixed in their meaning, but we need to
document that better. In general, clients should expect response
codes in accordance with the HTTP spec.
* clients definitely need to follow HATEOS principles, and use
links that they are given in responses from the server. There's
no guarantee that manually constructed links will continue to
work
> I understand the desire to pin down the API at an early stage, we just
> need to clarify how much working room we have within those boundaries.
Absolutely. We should probably refine this into something we can post on
the site.
David
