I was wondering how SaaS apps / enterprises notify consumers of your APIs of breaking changes / deprecation?<p>Is sending an email to the registered user account enough? Have some found that to be painful for consuming the exposed functionality?<p>Perhaps there is a convention for this sort of thing?
You should be versioning your API where possible, but I understand that's not always feasible e.g. when your API is not your main product. Regardless, I've always gotten email reminders about deprecations and upgrade paths. If you have customers using the API for business-critical things, you should absolutely version your API.
I don’t manage an API, but as a consumer of APIs that others manage, I can tell you that SOP seems to be “push breaking changes with no warning and often times no documentation.” (Even from very large companies you would assume know better.) If you send any kind of warning or advance notice you are likely in the top quartile already.
If you can, you should version your api, and if you didn’t yet you can start v2 with your new breaking changes.<p>I’d reach out via email to your users to migrate to the new version, and you can track how many are still using the old one. Timeline to move may vary, but I’d say that 3-6mo is relatively common.