
Ask HN: How do you notify API consumers of changes? - CaptainJustin
I was wondering how SaaS apps &#x2F; enterprises notify consumers of your APIs of breaking changes &#x2F; 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?
======
ezekg
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.

~~~
cimmanom
I just got bitten by a vendor that changed a business critical API twice in
three weeks with neither versioning nor notification. It's very
unprofessional.

I strongly second the recommendation to version customer-facing APIs. You
should never be releasing backwards-incompatible changes without giving
customers the option to upgrade on their own timelines (within reason - its
unreasonable to expect you to support an older API for a decade; 3 months is
an absolute minimum, though, and I'd recommend more like 18-36 months for
enterprise customers; and there can be exceptions for changes that address
severe security or data loss defects.)

And yes, at the very least, email communication is appreciated. Even if you're
versioning - if you have a customer using an outdated API, you should be
warning them that it's deprecated and then again a couple times leading up to
EOL.

~~~
bellt0wn98121
Do you pay this vendor? I'm trying to wrap my head around how a paid vendor is
so careless.

~~~
cimmanom
Yup, we pay them.

Support has since informed us that the announcement was in the monthly
newsletters we don't read because they're usually all marketing materials.

------
rajacombinator
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.

------
ecesena
If you can, you should version your api, and if you didn’t yet you can start
v2 with your new breaking changes.

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.

------
debacle
Version your API if you want enterprise customers.

~~~
IE6
While I agree with your sentiment I also acknowledge that implementing
something properly and having enterprise customers is often unrelated.

------
masudrhossain
When you sign up to use their api, you give them your email. They email blast
those peoples.

