The bad upgrade
Jim was writing this web site for his home recording studio, and he was using this product he bought off the internet that provides him with a lot of neat functionality. He can create a page once by adding controls to display his menu on the left side, and this other control to display his content in the middle, and then he can just log in to this administration tool and write his content. And he was very happy.
That was until he wanted to add a list of his studio equipment to the right site of the page. He read through all the documentation, but couldn't find any trace of a studio equipment control. So he decided to make is own. After he couldn't find what he needed in the product's API documentation, he started digging around in the libraries with his IntelliSense. He found a lot of weird classes and methods to use that would do funny stuff to his database of studio equipment, and he managed to hack together his control.
Now, the company building this product, SickSpence Web (6pW on the NASDAQ), didn't know they where going to have a problem soon. They where building this product using the JIT-D process, and didn't have time to plan everything they would do. They had just been told of this new functionality that was already sold and simply had to be implemented right away. Well, now Jim, and others too around the world, had started to hack together their own controls using the API. That would not have been a problem as long as 6pW where never to change any mehod signature in the API. But they were, and they would have a problem.
Jim heard that a new version of the product was out that fixed a lot of security issues in the previous version, and it was even a free download for existing customers! So of course he downloaded it and installed it. And then, boom! His web site went crashing down. Instead of his nice page with the animated gifs of spinning guitars and the midi background music, he just got this ugly page with an error message on it, "Invalid method call". He couldn't even get his sourcecode to compile anymore. And worse, there was no way to uninstall the upgrade. It had made changes to parts of the database schema, and there was no going back. Omfg! What were the guys are SickSpence thinking?!
Once it's released, you're stuck with it
Of course, the guys had noticed. Their support phone was ringing and their mailbox was filled with complaints. And unless you have a monopoly in your segment and customer support provides a large piece of your income, that is not a good thing. Now they understood why the book they had based their design on was stressing this thing about a carefully planned public API. They didn't want to do planning, it just didn't fit into their JIT-D process, so they had been quicly implementing the changes they needed to fix the security holes. And that meant changing the design of the API. They had to make some small changes in some of the undocumented methods that the controls where using, but they fixed the controls so this should not be a problem, right? Well, it seemed people had not been using only the documented API, but had found the rest of it through their IntelliSense. People didn't understand how lack of documentation meant they shouldn't use it. They had paid for a product, and they were darn well going to use it for all it could offer.
What I'm trying to illustrate here is the problem with API developement and backwards compatibility. Once you have, even if you didn't intend to, made public an interface - and there is even a remote chance that some funny customer with his own twisted ideas of hacking together a list of studio equipment or whatnot, would be using it - then that inteface cannot change. You are stuck with the design until you are willing to break you customer's code, or provide some conversion tool so they can upgrade their code to some new API that will replace the old one. This is what makes API design so hard. It requires good planning.
The only way around it is to force some legal aggreement in your EULA or some place, that states that if they use some API that isn't documented you cannot guarantee that it will work after an upgrade. But this brings a bag of problems with it. First of all nobody reads the bloody thing. And second, people will do it anyway and still expect the upgrade to work because that is how everything else works. And you don't really want to have this big reference client get upset with your product and start bad-mouthing you just because their developers weren't informed of the legal restriction on API usage. And third, it really just helps you half of the way because the part of the API that is actually documented still cannot change, and if the design is bad you're just as stuck.
Plan and separate
What you want to do, is to plan you API so there will be minimal design change. And any changes you do needs to be backwards compatible. That means that you don't add arguments to the signature of a public method, but you write an overload, and make the old method call the new one with a default value for the missing argument. You can also flag the old signature Obsolete, and provide a message explaining what other method should be used instead.
Also it's a good idea to separate the public API from your internal code. I mean physically in a different library, not just by what is documented and not. Have a set of classes in a public library that third party developers can use that are actually just calling into your internal library. Now you can change the internals without worrying about the public signatures.
When you have released some API that is just plain bad, you are going to have to live with it. You'll have to keep it around for as long as you want people to be able to upgrade without rewriting their applications. What you must do is to make a new and better planned API that you recommend over the old one and hope that all new customers will use it. Then, you can start to phase out the old API by sending out warnings that after some time the old API will no longer be supported. In the mean time you will have to maintain and support both.