incubator-deltacloud-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Toby Crawley <>
Subject Re: [RELEASE] Deltacloud 0.1.0
Date Fri, 17 Dec 2010 19:09:51 GMT

On Dec 17, 2010, at 10:22 AM, wrote:

> On 17/12/10 17:06, Toby Crawley wrote:
>> On Dec 16, 2010, at 6:24 PM, David Lutterkort 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. 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?
> not sure what you mean by 'the structure' - from where I'm standing its all of the above
- that is, the abstractions that we present (aka 'collections'/'objects') and their definitions,
together with the operations permitted on those (complete with definition of the inputs to
those operations, and expected output). This of course also defines the formats for the operations
and their results.
> With respect to 'clients' - well, we have already said we will maintain backwards compatibility.
So if your client implements *some* version of the API, the fact that links are 'hard-coded'
should be irrelevant - that is, they *should* correspond to/be compatible with whatever HATEOAS
links we expose under /api (assuming we maintain the backwards compatibility constraint),
> marios
>> 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.
>> [1]

A couple of thoughts on maintaining backwards compatibility:

* Does claiming backwards compatibility mean "if we make a change, and any client breaks,
it's our fault"? 

* Should there be an api versioning mechanism? If not, rigid backwards compatibility could
become a nightmare down the road.

* I suspect that backwards compatibility may already be broken between 0.1.0 and 0.1.2 with
the response code changes (meaning that deltacloud-client-0.1.0 can't properly talk to deltacloud-core-0.1.2),
though I haven't tested this.

* Another issue this brings up is with Deltacloud the API vs. Deltacloud the reference implementation
(deltacloud-core). I realize the backwards compatibility statement is for the reference implementation,
but without relaxing that or adding API versioning, it also forces backwards compatibility
on the API, since it can't change.

And with regards to HATEOAS - if it is the case that hard-coded links are supported, it goes
against the whole purpose of HATEOAS, as does including paths (/instances/:id) as part of
the API definition:

"The Deltacloud API is a RESTful API, using HATEOAS architectural style. The API requires
no client-side URL construction. Access is based entirely off a single entry-point resource.
This allows other implementors to structure their URL space however they like." [1]

"HATEOAS means that the hypermedia guides the clients' interactions. In other words, the hypermedia
responses from the API contain links which the client can follow in order to make further
requests. This also implies that the URI structure is not part of the API so the client does
not manually construct URIs and the server is free to change its URI structure in future.

If you find that you are documenting the URI structure and explaining how clients should construct
a URI, you are likely breaking this principle." [2]

I think it would be worthwhile to define a supported client as one that does proper HATEOAS
discovery, and define the API as what is returned by /api. I know it may be late for that
discussion, but now is better than later. 



Toby Crawley

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message