Devs, what tools do you use to keep track of API changes?

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!

Did you find this post useful? Show some love!

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

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.

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?


Hey there, we see you aren't signed in. (Yes you, the reader. This is a fake comment.)

Please consider creating an account on It literally takes a few seconds and we'd appreciate the support so much. ❤️

Plus, no fake comments when you're signed in. 🙃

We usually apply versión control over our apis, forma example:

You should never deprecate or introduce breaking changes on existing endpoints, instead better create a new versión like:

We let user choose her DTO response any way:

We use 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?

Classic DEV Post from Apr 11

What do you do on a daily basis for your job?


Follow @ben to see more of their posts in your feed.
Victor Bordo
Member since Mar 27, 2018
Trending on
Why do employers check job candidates' GitHub profiles?
How Art School Prepared Me for Programming
#art #career
Dev and Designer Communication
Who's looking for open source contributors? (May 21 edition)
#discuss #opensource
Go or Python and why?
#go #python #discuss
What kind of breaks do you take throughout the work day?
Developer Interview Bloopers
#career #development #interviews #php
How do you keep track of all the great resources you find?
#discuss #learning #resources