Hi Toby, On Fri, 2010-12-17 at 14:09 -0500, Toby Crawley wrote: > > 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"?
Within the bounds of our nascent definition of API stability, yes. For example, if a client breaks because they assume that a certain element has no attributes, it's the client's fault. If the client breaks becuse we removed an element from the XML, it's our fault. > * Should there be an api versioning mechanism? If not, rigid backwards > compatibility could become a nightmare down the road. I would like to avoid relying on versioning. The rest-practices guide[1] has some good suggestions on how to step the version of a RESTful interface without breaking backwards compatibility. > * 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. Ugh .. that would be a problem. IIRC, the response code changes addressed two issues: (a) producing 500's in some circumstances, something we should always feel free to break (b) replacing some 200's with 201's - what we are missing here are guidelines how clients should check whether an operation succeeded or not. My preference would be that they should look for 2xx response codes, rather than a fixed code. > * 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. I think what we're lacking is a little more formal definition of the API - it can't just be implementation, since implementations contain bugs (like the 200 vs. 201 response code fix) > 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: Yes, you are right; I assume you refer to the API writeup [2] - the URL's in there need to go; I mostly put them there to structure the document. Not sure how to retain the structure w/o reference to URL's. We'd need to talk about 'List images' and 'Get detail for an image' with an explanation of where you get the actual URL's when you talk to the server. David [1] http://fedoraproject.org/wiki/Cloud_APIs_REST_Style_Guide#Compatibility_and_Versioning [2] https://fedorahosted.org/pipermail/deltacloud-devel/attachments/20100812/8af80ac5/attachment-0001.pdf
