3 ms·

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 alwa

by ezekg 9y ago

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 9y ago
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.
- is_true 9y ago
  WTF? Is it something critical?
  - cimmanom 9y ago
    A hosted build system. It didn't bring our customer-facing business to a halt or anything, but it did grind our QA and deployment process to a standstill at a particularly inconvenient time.
- bellt0wn98121 9y ago
  Do you pay this vendor? I'm trying to wrap my head around how a paid vendor is so careless.
  - cimmanom 9y ago
    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.
iamNumber4 9y ago
Agreed, to add to this convention; having the version of the api as part of the communication protocol or message format is also recommended. This is so you can still support older api versions on the host side until a known cut off date. This allows for a soft roll out or smooth transition to the new version. There are various ways to implement, http header, http path, structured file formats to include a version variable, or meta tags, etc... This also allows you to put hooks in to track users of the old api version so that additional reach out/communication to the slow adopters can be had.

by ezekg 9y ago

cimmanom 9y ago

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.

is_true 9y ago
WTF? Is it something critical?
- cimmanom 9y ago
  A hosted build system. It didn't bring our customer-facing business to a halt or anything, but it did grind our QA and deployment process to a standstill at a particularly inconvenient time.
bellt0wn98121 9y ago
Do you pay this vendor? I'm trying to wrap my head around how a paid vendor is so careless.
- cimmanom 9y ago
  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.

iamNumber4 9y ago

Agreed, to add to this convention; having the version of the api as part of the communication protocol or message format is also recommended. This is so you can still support older api versions on the host side until a known cut off date. This allows for a soft roll out or smooth transition to the new version. There are various ways to implement, http header, http path, structured file formats to include a version variable, or meta tags, etc... This also allows you to put hooks in to track users of the old api version so that additional reach out/communication to the slow adopters can be had.