On Dec 17, 2010, at 10:22 AM, [email protected] 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] >> https://fedorahosted.org/pipermail/deltacloud-devel/attachments/20100812/8af80ac5/attachment-0001.pdf >>
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 [1] http://deltacloud.org/api.html#h1 [2] http://fedoraproject.org/wiki/Cloud_APIs_REST_Style_Guide#A_Word_on_HATEOAS --- Toby Crawley [email protected]
