Marketing materials from software vendors use the term API without context, which creates some ambiguity. This blog post provides an intentionally oversimplified perspective about traditional local APIs, which I refer to as libraries, and service APIs, which is the general understanding of APIs for scalable composable solutions today.

Defining APIs

API is an initialism for Application Programming Interface. APIs allow programs to communicate with each other, primarily to exchange data and invoke functionality in other programs. Read a comprehensive breakdown of "What Are Composable APIs?”.

APIs Aren’t New

Computer Software has always provided APIs that allow programs to interact with other programs running on the same machine, which I refer to as library APIs. An operating system such as Microsoft Windows provides a wide range of libraries that developers use to write programs to run on that platform. Enterprise applications have always provided library APIs so that developers can write code to extend, customize, automate, and otherwise interact with those solutions.

Service APIs

Service-oriented applications provide service APIs, which differ from library APIs in fundamental ways. Unlike library APIs that software programs use to interact directly with other programs, using facilities provided by the operating system on the same computer, Service APIs exchange data and instructions over the HTTP protocol, typically secured with HTTPS.

Service APIs are intended for interactions between different computers. Rather than operating-system-specific data formats, service APIs use JSON (JavaScript Object Notation), which is a generic text format for data representation that any system can use. In addition to JSON, service APIs use additional features of the HTTP protocol such as the URL structure and HTTP headers, and generally use HTTPS for secure communications.

Library APIs

Library APIs exchange data between programs on a single computer, such as a word processor. Library APIs can have simplicity, efficiency, performance, developer productivity, troubleshooting, and other advantages over Service APIs. Library APIs have various disadvantages, such as requiring applications to be built against specific versions of the library, which results in maintenance challenges for both applications and the libraries on which they depend. When a library changes, the application must be recompiled against the new version. For reference, research “DLL hell”.

Advantages of Service APIs

Service APIs have the advantage of spanning multiple computers that communicate over the Internet rather than within the operating system if a single machine. Service APIs are critical to scaling applications across multiple machines. Service APIs are appropriate for interactions between applications in and between computing clouds, where library APIs are only useful to programs running on individual machines in that cloud.

When a client invokes a service API, the HTTP request specifies the version of the service API to invoke. When a vendor needs to change a service API in a way that could break existing applications, it creates a new version of the service API. The owner of the client application can choose whether and when to refactor their code to use the updated version of the service API.

The Role of Software Development Kits (SDKs)

For developer convenience and productivity, many vendors of cloud applications provide Software Development Kits (SDKs) that function as library APIs that wrap their service APIs. Using such an SDK can defeat some of the value intended by service APIs. To use an SDK, developers must build the application against a specific version of that SDK, which re-introduces a dependency avoided by calling service APIs directly. Depending on such an SDK creates a tighter coupling between systems. If the vendor adds a version of the API, they must also create an updated version of the SDK, and developers must rebuild their applications against that new version. SDKs rarely cover every service API exposed by the vendor, so even when using SDKs, some programs must resort to calling service APIs directly. This results in code that uses two different paradigms to achieve similar functionality, which makes the solution more difficult to understand and maintain.

Closing Recommendation for Software Architects

Tying an application to a library API or SDK is a form of tight coupling that service-oriented applications avoid. Using service APIs still couples systems together, but in a much looser manner that allows for each to change independently.

For modern, scalable, service-oriented enterprise applications, I recommend that you avoid library APIs, even in the form of SDKs, in favor of service APIs. Use tools such as postman to experiment with and understand service APIs. At least for troubleshooting, it can be extremely helpful to know the details of how a service API works rather than how to invoke library APIs in an SDK. Beware of the drawbacks of Library APIs and SDKs.