Browse Prior Art Database

Build break prevention system / system to allow API changes unless they break a consumer

IP.com Disclosure Number: IPCOM000243538D
Publication Date: 2015-Sep-29
Document File: 4 page(s) / 58K

Publishing Venue

The IP.com Prior Art Database

Abstract

Described is a build/repository system enhanced with a registration system for API consumers to notify API producers about what APIs are consumed and builds an advance alerting system when a producer wants to make a change that will break a consumer (binary break) or may break a consumer (implementation break), that includes a variety of mitigation strategies for both the producer and consumer.

This text was extracted from a PDF file.
This is the abbreviated version, containing approximately 38% of the total text.

Page 01 of 4

Build break prevention system / consumer

Software projects frequently depend on other software projects. Each project may want to change at fast speeds, and when projects depend on each other, there is a chance for one project to break another by making an incompatible API change. This is especially prevalent in an organization where projects necessarily depend on nightly builds from other projects and build breaks are common.

Example: Project B depends on Project A. When Project A refactors a set of code including public API signature changes, their build will be successful but the next Project B build will fail. Better is if the breaking API change to cause the Project A build to fail, or at least provide advance notice to the A and B teams. There are two recognized ways that an API provider can break an API consumers code:

Through binary incompatibility. This is usually caused by the API provider modifying the


1.

API signature in such a way that the consumer's binary containing the API call no longer matches the binary signature of the API. For example, the provider adds a new parameter to the API or modifies the type or length of an existing parameter. The result of this binary incompatibility is either a runtime failure at the point of API invocation or a compilation failure when the API consumer attempts to build their binary that contains the API invocation assuming that the API can be directly referenced at compilation time. This second case is not applicable in the case, for example, of invoking a RESTful service. If the API provider follows the known and published rules of being an API provider, then a type 1 breakage should never occur. In simplistic terms, the rule is that you never modify the binary signature of an API. If an API has to change in a way that will break this rule, then the API provider should create a second API with the new signature and mark the original API as deprecated. A deprecated API has a limited life span and will eventually be removed. The API consumer must, within the life span of the deprecated API, migrate to the new API.

Through API implementation modification. This occurs when the API provider modifies the


2.

functionality of the API that results in a change in behavior and, therefore, result of the API invocation. For example, the API used to return the value '1' and now it returns '2' when the same parameter values are passed into the API. The second breakage should be the more common type of breakage.

There are simple rules of thumb to follow that mitigate API breakages and, in theory, prevent all type 1 (binary) breakages; however, these rules restrict development speed and can be overkill in the case of APIs that are not actually used. A system is needed that allows rapid iteration of provided software projects but at the same time prevents breakages of their consumers. Further, the system should assist with type 2 (implementation) breakages as well. Other API protection mechanisms...