We're constantly writing services, bots, and apps that include dependencies on external APIs. When those APIs inevitably change, we usually need to adapt to those changes. I've been in situations recently where my code breaks in production because of an API deprecation I wasn't aware of. How do you handle this situation? Do you use any tools or processes for API tracking? Curious to hear about your experiences!
For further actions, you may consider blocking this person and/or reporting abuse
Top comments (15)
Technically, I think we use customer feedback to keep track of API changes. Because when we accidentally change the API, we get a lot of angry customers telling us we broke the API.
There's got to be a better way.
That's an interesting way to go about it but probably not the most pleasant route :) for your company I'm sure. Can I send you an email with some follow-up questions? Curious to dive deeper here.
Sure, send me an email.
Hmmm, is there a "send someone an email" facility as part of this DEV site?
If there's not, let me do some lame email encoding to thwart the robots:
eljay (dot) adobe (dash) spam (at) gmail (dot) com
Remove the: (dash) spam
(That was some salt to thwart the smarter robots.)
Is swagger what you're looking for?
From my experience with Swagger, it's fantastic for automated documentation but doesn't have any pub/sub features for tracking changes to APIs/docs. Has that changed by any chance? I don't see any tools on their site for alerting and whatnot.
If the APIs developers publish a Swagger file and keep it updated you could just write a script to check if it changes using swagger-diff but I wouldn't count on it.
What if the Swagger has not been updated? What if the API doesn't have it all?
Another solution is to build it yourself. Use a "vcr" like tool, store the response and every once in a while check if the response you get it's still the same. If it's not, you can send yourself an alert and check.
It could have false positives but it might help.
You read my mind! I'm thinking about building my own but I want to see if it's a widely experienced problem before putting the time in. Based on the lack of engagement thus far looks like it's not a significant pain point :)
It could also be because there are no tools for it so people don't have an answer :P
It's hard to build an automated tool around it. Every API is different, you need to register each time to have the credentials and automating non idempotent requests can be tricky.
Also most APIs have clients which means that in numerous occasions the developer doesn't really know how the underlying HTTP API actually like (until it breaks :D). They might just read the client documentation.
Haha very true. It might be an interesting project to pursue. Good point regarding the underlying clients. I figure because there are so many unofficial clients that aren't maintained by the same provider of the core API and still used widely (Slack's unofficial library list is a good example) it might be a useful service for OSS maintainers as well. Thanks for your thoughts here I appreciate it!
We were recently hit with a very similar issue although it wasn't our fault (per-say). Our email service provider changed their User Interface, API & pricing model without any notice to their users, which we had to come in on the back end of and deal with countless clueless support team members to finally get an answer, the API access was ENTIRELY DISABLED because we hadn't bought the extra paid addition that was released with the new price model & UI. Let me know if you find any solutions to your problem as it is a pretty common issue.
tl;dr
it's (mostly?) down to the API provider to inform their users of any changes.
a good one will give you a nice heads up with plenty of notice, others will give you about a week...
take the new GDPR for example, and look at my inbox for GDPR related emails, it's been floating around since atleast december 2017 yet I'm only just getting notified for the changes to it 10 days before it comes in effect
Yeah, what a pain! How long did it take to figure out the issue? Do you mind if I shoot you an email to ask some follow-up questions?
Hi, I am creating a service that's exactly addressing this issue.
Here's a list of features:
Check it out and reserve your discount now at, a free account will be available to check the service for yourself ----> apipatrol.tech
We usually apply versión control over our apis, forma example:
Www.yoursite.com/v1/users
You should never deprecate or introduce breaking changes on existing endpoints, instead better create a new versión like:
Www.yoursite.com/v2/users
We let user choose her DTO response any way:
Www.yoursite.com/v2/users?dto=v1
We use iodocs github.com/mashery/iodocs for api documentation.Its quite old but does the job.Doesn't have many fancy features which swagger or apiary boast of but does the job
Good to know, thanks! Do you have any issues tracking changes to other APIs (external or internal) that your services depend on using iodocs?