API Connect

 View Only

What is an API? An Updated Definition

By Alan Glickenhouse posted Tue May 04, 2021 02:08 PM


universal power adapter
The definition of “API” (Application Programming Interface) has changed yet again!


In January 2018 I wrote “What is an API? And What is the API Economy?”, introducing a new definition for API.  That definition while still true has become incomplete.  But I’ve jumped ahead.  So, let’s start at the beginning…



Technical APIs complicated interface

In the earliest days of programming the term “API” – Application Programming Interface, came into existence.  These original “technical APIs” were often complex and always provider focused – i.e., focused on what the invoked program could provide when called.  The programmer wanting to allow others to use the application defines an interface to support the ability for other programmers to invoke the application.  The interface provides all the necessary parameters based on the capabilities of the program being invoked to allow a caller to execute the program and obtain the results.  A calling program uses a remote procedure call (RPC) to access this application interface.  Because the focus of the API is based on what the application can do, I am calling this “provider” focused – i.e., it is focused on what the application can provide to the caller.



Business APIs

This first technical API definition lasted quite a long time (decades) until the new era of the “API Economy” came about – starting approximately 10 or so years ago.  The new “Business API” or “Web API” that I discussed in the blog referenced earlier introduced the concept of a consumer-oriented API.  Rather than focus on what the providing application could do, this new Business API focused on what the calling programmer wanted to know / have done.


The Business API era followed after Service Oriented Architecture (SOA).  Business APIs solved many deficiencies in “services” that were a core concept in SOA.  Initially (maybe still?) there was much confusion about the relationship between SOA services and these new APIs.  I wrote several blogs positioning services and APIs – and later microservices as well (see here, here, here, here, and here). 


SOA Services were created to be the single source of truth about business constructs (e.g., customer, order, inventory, etc.). All projects needing information about customer, for example, need to use the customer service.  No longer are duplicate data definitions acceptable.  Because services need to support many use cases, the interface is often large and complex to handle all the different project requirements.  Services were most often built on web services technology (WSDL/SOAP) which is verbose creating very large request and response packages, typically sending far more data than any individual consumer needed.

simple interface 

Business APIs, being consumer focused, allowed the consuming application to request and receive only the information that it cared about.  APIs might access services to retrieve the result but tailored the response to only what was requested.  Business APIs were typically built using REST and JSON which was much lighter weight than the web service technology and allowed for easier to code requests and far less data returned. 


Additional infrastructure in the form of API Management software (e.g., IBM API Connect / IBM Cloud Pak for Integration) provided:

  • API lifecycle management – to make it easy to create and manage APIs
  • API Portal – to provide self-service consumption of the APIs for consumers
  • API Gateway – to provide security around the invocation of the API and protection for back-end systems.

All of these were lacking in the traditional SOA infrastructure.  The combination of APIs and the API Management infrastructure addressed many of the deficiencies in SOA.


 more and more

APIs are Great But Can We Do More?

APIs and API management provided significant business benefit – and continue to do so.  In fact, the success led to the need to expand the definition as we try to do more things using the same approach that we used for these business APIs.


  • Customized Business APIs
    As APIs become more frequently used the number of permutations of consumer-oriented requests for data that were close - but not exactly the same, starts to become unmanageable. How many nearly identical variations is the company willing to maintain?  Some businesses chose to standardize on different levels of granularity (e.g., a small amount of info returned, a medium level, and a large level).  But this starts to diverge from the purpose of a truly consumer-oriented solution, leaving the caller to parse through information they may not care about.  The solution to this is GraphQL.  GraphQL allows the caller to specify which data items they want returned, keeping the API call and data returned specific to the consumer.  A single GraphQL API can handle many different variations.  While the call itself becomes a bit more complex it allows for variability without a runaway number of unique APIs.  Adding the ability to manage GraphQL into the API Management solution provides the ability to enable consumers to use the portal to consume the API, manage the GraphQL API lifecycle, and secure the GraphQL invocation.  This puts another tool in our API toolkit to use when appropriate.
  • Asynchronous APIs and Events
    Business APIs using REST/JSON follow a synchronous request/response model. As the number of API calls increase, the load on the back-end applications is also increasing.  An alternative asynchronous model allows for back-end applications to publish information as it changes to any application that might care, thus allowing a single publish action to support many potential consumers (subscribers).  Kafka has become a very popular option to support this model.  Managing events in an API Management solution enables the same well-known self-service consumption and security management to events that we have previously used with REST/JSON.
  • Low overhead high speed connections
    Another variation supporting clients and servers who are known to each other and need high speed with low overhead might use gRPC.  gRPC is a lightweight protocol making it very applicable to situations where there are low powered clients where there are not significant computing resources.  IoT devices such as smart meters, smoke alarms, smart light switches are examples where this might be of use.


As we think about business scenarios it is often the case that multiple interaction patterns are used between the same consumer and provider.  For example, in my bank app I log in to check my balance (REST) but they send me an alert when my credit score gets updated (event).  With an airline, I log in to see if my flight is on time (REST) but they ping me when I get the free upgrade (event). 


Many solutions use multiple interaction patterns.  As businesses trying to enable the creation of these solutions there is benefit to both the consumer (internal or external) and provider if we manage all the interaction patterns consistently.  Applying traditional API Management strengths for life-cycle management, consumption, and security to other protocols beyond REST provides consistency, efficiency, and increased productivity.


GraphQL, Events, and gRPC are just a few examples but there may be many more that might make sense.  Why not manage WebSockets, MQ queues, or even files using the same approach that we use for APIs?  Consuming developers and API providers both benefit from consistent management, consumption, and security across interaction models.


Multi-form Business APIs – An Updated Definition tools

As technologists we often see the technology first – REST, GraphQL, gRPC.  I have tried to reverse the perspective to focus on the business benefit that the technology supports as the primary focus.  This is core in coming to the new definition for APIs.  The definition we have been using for “Business APIs” needs to expand to handle these new scenarios across multiple styles of interaction - multiple API tools we can use.


What has not changed:

  • Business APIs” are simple to understand interfaces focused on business recognizable assets – e.g. a product, an order, a customer, etc. 
  • Business APIs are focused on providing a secure, easy to consume interface targeted toward the consumer of the API, not the provider application(s). 


What is changing:

  • APIs were strongly associated with REST / JSON, some might have included SOAP / XML as a second option.
  • API implementation options are expanding. Now there are many additional styles of API: Events, Async APIs, GraphQL, WebSockets, gRPC, and even Files may be treated as Business APIs.


The new definition for an API separates the purpose (why?) from the implementation (how?).  The definition specifies the purpose of APIs and specifically does not address the technology used to implement.  This provides a broader definition that can expand to support many interaction models. 


Here is my suggestion for the new definition of an API –

“APIs allow business assets to be securely and easily consumed and used by developers.”



If you have questions, please let me know.  Connect with me through comments here or via twitter @Arglick to continue the discussion.  


Graphics courtesy of Pixabay.com – geralt, pixel2013, and Maria_Domnina