On 2013/9/23 5:08 PM, Richard Newman wrote: >> Q: What about putting the version in the body? >> A: This is why your developers and QA hate you. In order to do this, >> they need to make sure that existing code supports multiple, often >> conflicting versions or does complicated back end hand-offs, increasing >> the testing systems and other things that are the direct opposite of >> what they live for. > > I should add to this: very, very often the code that handles some record > object is far away from the code that speaks the wire protocol. And very > often the service is a storage service, and thus can end up storing records > of multiple versions (if only due to bugs). > > For this reason I'm in favor of *also* versioning stored records. But that's > a very different thing to putting the wire protocol version in the body of > uploads or downloads. > Sadly, this is where English fails us as an appropriate language for discussing things like this.
"Version" is a multiple term in this case. For my discussion, "API Version" is what is placed in the URL. I'll presume that "Data Version" or "Interface Version" is what rnewman is discussing and is a function of the calls made to the API version. One can presume that should a the Foo storage method change the structure of the data that is being exchanged, that this may trigger a Data Version change, where if the Foo storage method was being removed or replaced, this would trigger an API version. It is important that this sort of thing be clearly delineated and defined in the protocol documentation. The lot of the API developer is that the majority of folks out there are gleefully illiterate, and will invest the least amount of reading and effort in getting something that works. Having clear, simple, consistent docs help customers avoid paths paved with dragons. _______________________________________________ Sync-dev mailing list [email protected] https://mail.mozilla.org/listinfo/sync-dev
