Evaluate Weigh the pros and cons of technologies, products and projects you are considering.

Goldilocks and API granularity

Microservices, containers, and APIs, oh my. They are the holy trinity that anoints cloud and mobile computing with unfathomable power and limitless scalability. APIs are the glue that hold the others together and make possible a universe of interactions with services, applications, analytics, and data from well, from anywhere and everywhere.

It makes sense, therefore, to want an API to do as much as possible each time it is called. Do more with fewer calls and you maximize efficiency, right? Maybe, maybe not. Ok, let’s try the converse, an API that does one tiny, highly focused task when called upon. Do less with each call and you boost speed. Again, maybe, maybe not.

Just like two children of differing weights, seeking that one golden location on each side of a see-saw fulcrum that places the overall system into magnificent equilibrium, APIs are not really any different. Find that magical balance point between too many small calls and too few big ones, and you’ve built a work of art. It’s the Goldilocks effect brought into the cloud age.

One of the world’s top API experts calls it API granularity. Manfred Bortenschlager, Red Hat’s director of business development for API-based integration solutions and API management, says developers need to get better at it.

“One thing that’s difficult to get right is API design — in particular, the right granularity. An API could give you a lot of data back; a lot of values, which are potentially unnecessary; or just too much data,” Bortenschlager says. “If you are serving a mobile app, this could be too much payload. On the other end of the scale, you could have an API that gives you too little back. This means that an API consumer would have to issue many API calls. Getting this balance right is tricky.”

APIs don’t exist in a vacuum. An application can easily encompass several dozen. Though each performs one task, all of them, when taken together, must be designed for optimal system performance, resulting in a speedy and enjoyable user experience. Many small API calls can get hung up on network latency that drives users crazy. Fewer, bigger calls require fewer round trips, but may return data or metadata that’s simply not needed, slowing down an application. On mobile devices, these small delays can be deadly, leading to session and user abandonment. Not too big. Not too small. Goldilocks.

Version control

A separate issue, but no less important, is that businesses publish APIs that allow their customers to gain access to data or services. It’s a fact of life that software gets updated and that you’ll never, ever get all users of an API to be on the same version at the same time. (How many are still running Windows XP?) Some may upgrade today, others not for months, still others not at all.

That means maintaining tight control over versions is essential. And it’s not easy, according to Bortenschlager. “It’s impossible to have an API with changes that never break. It’s impossible. That’s just the nature of it,” he told me. “What’s important is to communicate changes very well and far in advance.”

Through API management, Bortenschlager says, it’s possible to know exactly who is using each version of an API. “If you know that you are going to change a subset of your API to a new version, you can target the communication to those developers in advance,” he says. Good advice.

How does your company manage its API assets to ensure that those used in an application are efficient and compact? And how do you deal with the headache of having multiple versions of an API in use simultaneously? Share your thoughts; we’d like to hear from you.