As the number of APIs in an organisation increases, maintaining API contract consistency should become a design time goal, but how do the benefits outweigh the cost?

The first article in our Increasing the Quality series, we discuss the implications and benefits of managing design consistency across a whole organisation’s APIs.

With the imminent release of the last film in the Star Wars saga, the excellent StarWarsUncut fan remakes can provide some fan-tastic (see what we did there?) context to how inconsistency in APIs can distract from the vision and value of the overall API strategy.

For those who don’t know, StarWarsUncut is a collaboration of thousands of independent amateur filmmakers and artists who are allocated a 15 second section of one of the original Star Wars movies to re-create in whichever style they desire. Some act, some animate and others use models, each using their fortes to create the best representation of the original George Lucas vision they can.

Check it out if you have the time –

It is not difficult to draw parallels between the StarWarsUncut films and the API catalogues of large organisations, where disparate development teams create the best they can using their individual skill sets and knowledge. Technically the APIs fulfil their requirements – i.e. their tests pass – however, like the fan films, when consumed alongside other APIs they collectively present a disjointed offering that wield integration challenges further down the line – certainly not often representative of the joined-up vision that the organisation’s API strategy intends.

But why does API consistency (or lack of) have an impact? The answer lies in the concept of familiarity,particularly the trust and confidence it brings for consumers. As humans, if we have completed a task before, we have a greater confidence that we will be able to complete another, similar task, in a shorter time or with greater ease. APIs are machine-to-machine interfaces and therefore app developers are the only human element of interaction with an API. Providing developers with an API that they find familiar to ones they have previously utilised (either in its use of industry standards or similar structure and nomenclature) gives them a greater sense of confidence as to their success with integration.

Within organisations that produce significant numbers of APIs, the consistency between contracts also yields benefits in the form of code reuse in implementations and tests, enabling knowledge transfer between project teams and reducing effort needed to align metrics when analysing trends or performance. All of these benefits translate into reduced development and operational risk for the organisation’s APIs.

At Apiway we have found that the key to consistency is continual, gentle guidance/persuasion provided to designers during the design phases. Certainly this is better received and less risk to projects than a heavy-handed alignment enforced by a governance process at the end of the design cycle. However this approach can cause logistical difficulties for design teams and governance functions alike, as there needs to be a continual back and forth to check and re-check the API design against the established standards.

Thankfully the process of design guidance can, with the correct API ecosystem, be automated and this speeds up the process without tying up resources. For API designers the automated instant feedback, for even partially created API Contracts, becomes part of the design tool-set along with business and security guidelines.

Wrapping up

The result of consistency in APIs is greater consumer uptake, simpler integration, lower costs and quicker time to market – Making it an essential goal of any organisation with bold API aspirations.