what I learned from shipping APIs:

1. Clients will do whatever they need to do get their job done, even if it's not the publisher's intended way

2. Clients don't read documentation

3. Bugs will become part of API once enough clients rely on their behavior

4. The number of API calls does not necessarily equate to importance.

---

As such, I aim for the following when developing an API

1. Ship the beta API early and see how they use it to minimize the surprise. (This may not always be possible)

2. In most cases, bump up the major version while supporting the previous version. This means you'll need to define SLA for your API

3. Most clients are OK with breakages as long as they are given enough time to migrate, or the API provider gives them a tool to auto-migrate the code (if that's possible in your product)