There are a few good reasons why almost every AWS API is on V2. Firstly, the earlier ones were the Wild West and took differing approaches to things. A good ex

There are a few good reasons why almost every AWS API is on V2. Firstly, the earlier ones were the Wild West and took differing approaches to things. A good example of how things were is SimpleDB, one of their first public APIs, which uses SOAP. Amazon later changed how they did all this, standardising things and switching to JSON for serialisation along with standardising parts of their request and response format, and that means that many went to V2 just because of that. And as somebody who's ex-Amazon, you should know that better than me who's just looking in from the outside. Heck, it could be that somebody pushed them to release something before the details were nailed down. I've had projects like that where we were forced to release an API for general use internally before we were happy with it, which lead to us having to do a V2 that should've been our V1. This happens too. Also, the fact that a service is on V2 doesn't bother me that much. That means that they went through one set of breaking changes after their first public release. If that major version number were higher, I think you might have a point. If they've stuck to that and have just been bumping the minor revision, that means they've just been adding features. > Clearly, documentation is not a silver bullet. It's not meant to be. Nothing is, and that's not the point that's being made. That doesn't mean that it doesn't help an awful lot, even if is agonising torture. If you can't write down what you're doing, you probably don't know or understand what you're doing. Narrow your scope to what you do understand, and specify and implement that. Scope expansion is what minor version bumps are for.