Five habits of highly effective APIs

With no design sense, discipline or governance, API usage can easily spin out of control.
Written by Joe McKendrick, Contributing Writer

Open or web APIs can help reshape and improve the competitiveness of organizations, opening up or providing access to a range of functions and services. Or they can lead to huge, tangled, and over-duplicated messes.

Photo: Joe McKendrick

As API consumers, businesses now have a choice of almost 15,000 open or web APIs, according to the latest numbers from the ProgrammableWeb API Directory. Most businesses will also be creators and publishers of APIs, whether they be for internal processes or for consumption by partners, customers or ecosystem members.

With this in mind, APIs need the same care and planning as any piece of software that is produced. That is, they need to be created with a business need in mind, be secure, and well governed. As Julie Craig of Enterprise Management Associates and Reza Shafii of MuleSoft point out in a recent work, APIs are a reflection of the business, and will also represent a key part of the workflow. Their observations were part of Ross Mason's latest chapter book, First Break IT: How Composable Services Are Changing the Role of the CIO. (Disclosure: I wrote two chapters for the book as part of recent project work with MuleSoft.)

"While it's relatively easy to provide or consume APIs, the number of API connections that an organization uses tends to grow very rapidly," Craig and Shafii state. "As more users and more applications connect, and as development creates new APIs and versions, the API landscape can start to look more like a maze to be navigated than the straightforward way to flexibly extend the business."

Craig and Shafii point to five considerations in achieving an ideal state for APIs:

Well-designed: "First and foremost, the API needs to be designed in such a way that the consumers of the API will actually want to interact with it," Craig and Shafii say. "The better designed that API is, the more easily it makes the data behind that interface accessible to the consumers and therefore makes it successful more rapidly."

Well-implemented: Here's where all that hard work around service oriented architecture, microservices and enterprise integration pays off. APIs "must be built on a reliable, scalable, and highly available foundation and it must be easily integrated with your existing back-end APIs and services and assets, whether legacy assets or not, that you already have," Craig and Shafii advocate.

Consistent: Often, as a classic example, security schemes may be implemented in multiple ways in the enterprises. "That makes the life of the API consumers very difficult, but it makes it hard for the API providers as well because they have to go and reinvent the wheel every single time around implementing a security scheme," Craig and Shafii say. "Consistent design,enabled by IT, then, is key to make API-led connectivity work."

Discoverable. "Developers need to be able to easily find what APIs within the organization are available for them to be successful," Craig and Shafii point out. "But in many cases, there are only various spreadsheets or various Wiki pages spread around documenting that there's an API. What companies really need is a central place where all the APIs are actually exposed and can easily be searched and used from there."

Complementary to the existing architecture. "It's all about reusing existing assets and business logic," Craig and Shafii state. "What API-led connectivity does is transform the present investment in IT architecture, whether it's assets, mainframes, data and databases or big data stores, legacy middleware that might exist or any custom applications. These assets present very valuable sources of information within the organization." The challenge is making this data available in a highly consumable manner to the stakeholders who need it.

Editorial standards