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.

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?

Ben Halpern DEV.TO FOUNDER

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

Please consider creating an account on dev.to. 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:

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?

Classic DEV Post from Apr 6

What is the job of a consultant?

Whether a solo consultant or part of a consultancy, what would you say a consul...

READ POST
Follow @ben to see more of their posts in your feed.
dev.to is now open source!
View Announcement Post View GitHub Repo
Victor Bordo
Indie hacker with a background in software development, SecDevOps engineering, cloud architecture, project management, and consulting 🤔
Trending on dev.to
What are your thoughts on multiples package managers?
#discuss
How to take breaks while coding
#productivity #learning #career
What is the simplest code to explain a loop?
#basics #anylang #discuss
Explain Blockchains, Cryptocurrencies Like I'm Five
#explainlikeimfive
What's the deal with downing PHP development?
#discuss
How does the web look if everyone owned their own data?
#discuss
Open Source Has Not Failed. Don't Cover Up Corporate Abuse of Open Source
#opensource #technology #career #rant
What are your favorite terminal apps or scripts, to use for productivity?
#discuss #python #bash #productivity