My apologies for replying out of thread. mailman is having issues, apparently.
Hi all, I've got a pretty storied history dealing with APIs, both as a consumer and creator of them. I've dealt with not only every sort of version implementation, but with the fallout of those choices. If I may, I'd offer the following suggestion which will cause the least number of developers being degloved by an angry mob. If I may, I would suggest the following: https://host:port/v1/service?key=value... First off, let's talk about API versions. These are not reflected into the URL, but are more meaningful for service providers and developers. This is how you associate documentation and features to code. Your version is: Major.Minor.Build Major - Introduces at least one non-backwards compatible function that will break clients. This is non-negotiable. There are no "small" changes. Since your unit tests are based on your published API (they are, right?) if they break, you change your Major. Minor - Introduces at least one new feature or function that adds to the existing API. Build - Fixes a bug to bring existing elements more inline with published specifications. The URL value contains only the Major version. Why? Because if you add a new feature, you're not breaking anything. If the feature didn't exist before, then older clients will never have called it. If you are breaking something, you're using a new Version. Versions can be sunset. Ideally, with proper announcements and some out of channel means to alert developers that they need to use the new verison. An old version should be maintained for at least 6 months (far longer if this is used by commercial systems that have long product cycles), but after that, it is up to the kindness and discretion of the service provider. Q: Why put the version in the URL with a "v" prefix? A: using "v" indicates an explicit version, and the numeric indicates what MAJOR version you're using, since you are NEVER breaking function by introducing a new minor feature. Right? Adding the "v" makes it explict to both you and your customer. Q: What about putting the version in the headers? A: Ok, so what version does a user get if they don't specify the Header? What if their client can't get headers or they're stripped by a firewall? Yeah, you make it explicit for everyone. 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. Q: What about putting the version in the hostname/port/other location? A: This is why your ops folks hate you. In order to do this, they need to modify DNS servers, wait for propagation, trust that clients will pick them up, and possibly get new SSL certs for the boxes. Do not make your ops folks hate you, they're very nice people who can make your life a living hell. Q: I've got a fix that changes the returned data from a list to a hash or changes the names of two things, that's a minor change right? A: No, it's not. Unless all possible reading code can deal with the change without any impact or modification, it's a major change. This why you spend a long time thinking about your API rather than rush crap out after a night of drinking. Hugs and here's hoping the angry mobs don't come calling. _______________________________________________ Sync-dev mailing list [email protected] https://mail.mozilla.org/listinfo/sync-dev
