My bad, API -- Tibco digital platform lead defines a ‘bad API’
An API is an API is an API, right?
No, it’s not that simple… and here’s why.
As we have explained before now, an Application Programming Interface is code that allows two other pieces of software to communicate with each other.
The API defines the correct way for a developer to write a program that requests services from an operating system (OS) or other application – and APIs are implemented by function calls composed of verbs and nouns.
So if not all APIs are created equal, then how do software-centric data-driven businesses ensure their APIs are all beautifully architected, successfully implemented, well categorized, thoroughly tested, robustly secured and… most crucially of all, able to actually fulfill the function that they were designed to execute.
Director of digital platform strategy at Tibco Software Inc. Rob Zazueta has laid down some of the key ‘bads’ that an API can exhibit.
Zazueta came to his role at Tibco as a result of the company acquiring API management platform Mashery. Tibco itself is a data and API management and integration specialist and its products include the Tibco API Exchange Gateway, a technology set designed to provide an event-driven web services platform — this company knows about APIs.
“API producers must apply the same level of care and detail to the design and developer experience of their APIs as they do to the design user experience of their corporate web sites and browser applications,” said Zazueta.
The following text results from an interview with Zazueta at TIBCO Now 2018 — it is has been edited for technical accuracy by Zazueta himself and is thus wholly attributed to him.
API bads
Too chatty – a bad API can be one that is too ‘chatty’, requiring a client application to have to make several calls to accomplish simple tasks that could be combined into fewer endpoints without violating the best practice of keeping resources independent and decoupled from specific use cases.
Too bloated – a bad API can be one that is too ‘bloated’, that is – the response payload may be overloaded with information that should be broken in to several endpoints – as such, it brings back the required information, but a whole load of other extraneous information as well.
Poor data payload design – a bad API can be one that exhibits poor data payload design, this makes it difficult to parse for a machine, complicated to read for a human developer, fragile, potentially likely to break and inefficient in terms of its speed, ability to transport and more.
Bad scale – a bad API can be one that fails to scale, that is – it is built with the assumption of lower usage which drags the entire system down as adoption grows.
Poor error reporting – a bad API can be one that returns 404 not found errors for every problem it encounters rather than using robust error reporting, either adopting the HTTP error code standards or some clear, customized error scheme that gives the consuming developers a chance to understand what went wrong while alerting the API producers to where the error occurred.
Inconsistent schemas – a bad API can be one that doesn’t standardise on simple things like parameter names, where, for example, one resource returns a customer’s given name as “first_name” while another lables it “fname”.