What Breaks APIs?
Written by Ian Elliot   
Wednesday, 17 January 2018

There is so little information about how we actually code that almost any data is worth looking at. In this case the study is on how and why Java programmers break the APIs that they are creating and evolving.


We all know that APIs change and fixing software that has been broken by some library upgrade is a fact of life - but why? Why do programmers, who also understand the importance of not making breaking changes, feel the need, nevertheless, to make them? This is the question asked by some recent research by Aline Brito, Laerte Xavier, Andre Hora and Marco Tulio Valente that is to be presented at the  International Conference on Software Analysis, Evolution and Reengineering:

In this context, one important question is not completely answered in the literature: despite being recognized as a programming practice that may harm client applications, why do developers break APIs?

The four precise questions they set out to answer are:

  1. How often do changes impact clients?
    39% of the changes investigated in the study may have an impact on clients. However, a minor migration effort is required in most cases, according to the surveyed developers.

  2. Why do developers break APIs?
    We identified three major motivations to break APIs, including changes to support new features, to simplify the APIs, and to improve maintainability.

  3. Why don’t developers deprecate broken APIs?
    Most developers mentioned the increase on maintainability effort as the reason for not deprecating broken APIs.

  4. How do developers document breaking changes?
    Most developers plan to document the detected breaking changes, mainly using release notes and changelogs

The team monitored 400 Java libraries hosted on GitHub for 116 days. They detected 282 possible breaking changes and got responses from the developers of 55% of the libraries.

Follow-up interviews revealed some additional interesting facts. Most of the breaking changes were due to the programmers refactoring code.  A surprising number of programmers claimed that the changes were to internal utilities that were never intended to be used by the outside world.

As to the exact reasons for the breaking changes, the four most often quoted motivations were: New Features, API Simplification, Improve Maintainability, and Bug Fixing.

Overall it seems that the developers valued the improvements in their code and library above the need to maintain the API's contract with the outside world. They appeared to reason that the impact of the changes on their users was small and the benefits to them outweighed the loss of stability. There is some evidence in the research that some of their clients agreed with this attitude, citing the effort needed to migrate to the modified API as being "minor".

It is surprising to find such a lax attitude among programmers creating libraries for consumption by others. However, I'm sure you can think of important APIs that seemingly break the rules simply because the development team decide that they can do the job better. Perhaps the biggest recent example of this is the move from Angular.js to the non-backward compatible Angular. It is also surprising that lack of encapsulation is quoted as a reason for not realizing that an internal change had an external consequence.

What can we do about it?

The researchers suggest that the tool that they used to detect changes, APIDIFF, might help library builders to realize what havoc they are about to wreak by listing potentially breaking changes.

Fundamentally, however, despite years of work on versioning of both code and interfaces, it seems that programmers just value their own work more than any impact it may have on the outside world. Starting over because now we know how to do it right is a common programmer failing. It also seems that the same failing applies on a smaller scale.


More Information

Why and How Java Developers Break APIs

Related Articles

Does Strong Typing Help?

Automatic Testing - Programmers Are Still The Problem

Code Digger Finds The Values That Break Your Code

Debugging and the Experimental Method       


To be informed about new articles on I Programmer, sign up for our weekly newsletter, subscribe to the RSS feed and follow us on Twitter, Facebook or Linkedin.



Apache Updates Geronimo Arthur

Apache Geronimo Arthur has been updated with support for Common-compress, XBean, and ensures the default options are compatible with last GraalVM release.

Amazon Ending Alexa Skills Payments

Amazon has told developers who are signed up to the Alexa Developer Rewards Program that their monthly payments will end at the end of June. The announcement follows a decision to end the program unde [ ... ]

More News

raspberry pi books



or email your comment to: comments@i-programmer.info

Last Updated ( Thursday, 18 January 2018 )