An API is a system that connects computers or computer programs. To access an API, an application calls an API, and the API sends back a response. This is a common way for apps to retrieve data from external sources. By using APIs to access reusable functionality, developers don’t have to reinvent the wheel whenever they need to insert specific functionality, such as payments, authentication, or geolocation. APIs have been around for decades, but when we discuss APIs today, we’re usually talking about web APIs that work over HTTP.

APIs are the bedrock of many apps we use daily, and they have become products in their own right. The programmability of APIs can help extend platforms in innovative ways. And today, as nearly every company embraces digital transformation, most utilize some sort of internal API. The decoupled nature of an API-first approach helps retain evolvability, helping to adapt to new devices and platforms over time. But not every API is equal — successful APIs require good design, quality developer experience, and ultra-tight security. Also, since end-client applications depend on the integration to function, the API must remain stable to avoid breaking changes.

For these reasons and more, APIs have become connective tissue for modern software, extending software functionality and connecting microservices architectures. Yet, when discussing technical topics like APIs, we tend to take many industry terms for granted. We often throw out words as if they’re easy to understand and universal. But, these terms often reflect quite a complex lineage of development and industry thought. This is no less true of the API space, where APIs are often discussed at great length while rarely providing a coherent narrative on what an API actually is.

Below, we’re going to attempt just that. We’ll dive into what an API is, what constituent parts it’s made of, and provide some analogies to help understand APIs at a basic level. We’ll explore some history, as well as note two major paradigms of API design.

What is an API?

One way to define what APIs are is to express them as a metaphor. Imagine that you’re an electrician on a construction site for a large building. As you work on this building, your work will intersect with many other roles. These roles have their own dependencies, deliverables, and goals that ultimately feed into the larger construction process. Deliveries, regulations, placement guides — everything on a site depends upon communication between groups of specialists, adding up to something greater than the sum of its parts.

Now imagine that complex system, but with a workforce where everyone speaks a different language. Without a common language or a translator, there is no real ability to communicate complex topics between each unit. Wouldn’t it be helpful to have a system to bridge this communication gap between the disparate systems? Such a service would better everyone’s efforts and allow for much higher-order functions.

This is the core value proposition of APIs. They are like a lingua franca for contemporary software. Computers, and computer programs, are very much like the elements of our theoretical construction site, each designed to do a specific thing for specific purposes, and all unable to communicate with each other without some sort of intermediary. How these components communicate dictates a lot — it can alter efficiency, efficacy, and fundamental function. Accordingly, these systems and their additive output will only be as good as their interconnections.

The takeaway is simple. At its most basic, an API is a technical tabula rosa that allows devices and software to talk to each other and communicate their intent, function, and form. What actually makes up an API, though?

Components and Implementations

‘API’ often refers to a single offering, but APIs are not just a communications layer or a simple interface program. While that may be the final value proposition, the reality is that APIs are the sum total of many integrative parts. For example, an API may be composed of many individual endpoints and methods.

For an API to work, it needs some supportive infrastructure. The specific way in which these systems work, as well as how the interface is used, is referred to as the API specification. This specification is a mixture of “how was this built” as well as “how to use it,” and serves as a sort of primer and continuing guide. Popular API specification standards include OpenAPI and AsyncAPI. When that specification is utilized to build out an offering, that is then referred to as the implementation.

An API is really a collection of many calls and functions, constituent parts that each do a specific thing. A call is essentially an instruction to the internal system to do something. For instance, GET is a commonly used HTTP verb that tells the system to retrieve something and render it to the user. When a developer accesses a specific location to invoke these calls and functions, they are said to be touching an endpoint of the function.

These terms are often used interchangeably, but note that endpoints are specifically used to refer to the edge of the API where requests happen. For instance, the endpoint may be api.com/getdata for the function getData. While getData might use other internal functions, the actual user ingress happens at that endpoint specifically.

Interoperability and Standardization

APIs often implement some form of standards around their endpoints and codebase. Adherence to these standards will guarantee a higher level of interoperability, allowing APIs to communicate with one another in an agreed-upon form. Not only does this enable APIs to communicate, but it also allows them to leverage the strengths of supporting tools, resulting in greater form and function.

A related concept is the idea of microservices. The microservice approach takes the value of standardization and replicates it through a collection of smaller, lean APIs. This collection of micro-APIs can isolate systems, resources, and functions from each other. How would that be beneficial? Let’s look at an example.

Imagine a hotel booking service built out as an API. In the traditional monolithic approach, this service might have a customer record system, a payment system, room management systems, and more under the same roof. All requests are handled by a single API carrying out all of these diverse functions. This method incurs some negatives — any time you want to change a single system, you have to alter the entire ecosystem, which can be expensive and time-consuming. Similarly, any failure in one part is likely a failure across the board.

Instead, a microservice-based approach would create a standardized network of APIs, with the customer record system being its own API, the payment system being its own API, and so forth. By separating each API into its own microservice, services can be isolated, making rapid iteration much easier. Additionally, if there’s a failure, that failure is isolated to where the problem exists, not across the entire monolithic API.

One point worth clarifying — when all of this is done over the network, this is called a web API. Web APIs in the online space are often used synonymously with the general term API, but there is a difference worth clarifying.

Design Paradigms

There are two main design paradigms in the API space today, and as we define APIs more broadly, it’s helpful to put the concept within these two strictures. SOAP and REST have both become so ubiquitous that, when someone references using “an API”, the next question tends to be about the specific paradigm at hand. Let’s briefly look at these two paradigms and how they change the API experience.

SOAP, or Simple Object Access Protocol, was created in 1998 by Dave Winer and others in collaboration with Microsoft. The standard quickly became the paradigm of choice in the enterprise environment. Given that the enterprise had such a hand in guiding early development, this is reflected in modern SOAP APIs steeped heavily in enterprise-specific features. SOAP is quite formalized and structured. This formalization and heavy structure deliver some major benefits in some use cases, notably when securing messages in transit (for example, in a situation such as online banking).

Unfortunately, this extra overhead and structure that gave SOAP such a promising start is a major contributor to why alternative paradigms are needed. While extensible, SOAP suffers from overhead costs that are just too expensive for simpler processes. While it does operate over HTTP as a transport method, it’s not closely coupled. While SMTP, TCP, and UDP can be used, this can cause some limitations, making it relatively inflexible. This inflexibility is somewhat made up for by derivative technology atop SOAP. Still, ultimately, SOAP is a paradigm with a specific use case — when the developer needs explicit and high-level control of the API and all requests which filter through it.

RESTful API design was first created in 2000 by Roy Fielding at UC Irvine. The concept behind REST, or Representational State Transfer, was to create a pattern by which web architectures could be defined through uniform interfaces that were transformable, mutatable, and extensible by design. In this initial treatise, Fielding stated several constraints that were meant to form a communication architecture. These requirements, generally, are:

• The establishment of a client-server relationship (a concept that is commonplace on the web today);
• The requirement to remain stateless (that is, the session data sent can be understood in isolation and doesn’t require the server to maintain a state);
• Cacheability, where responses can be marked as either cacheable or non-cacheable, and responses can be stored for future duplicate calls, thereby reducing or even eliminating many client-server request patterns;
• A layered system, where each element can be separated without affecting the communications of the systems or requiring client or server code updates; and, perhaps most importantly
• A uniform interface for standardization communication, easy extensibility, and independent iteration and development.
• Note that there is an optional “code on demand” constraint in which servers can expand and extend clients by transferring code. This is entirely optional, however, and as such is often not quoted as a constraint.

Ultimately, both of these paradigms exist for very different purposes.

REST is a lightweight approach to web design and boasts a wide range of features that makes for extensibility and rapid iteration. While REST is not as strict as SOAP — in many ways, there’s almost no standard definition of what REST is outside of the dissertation from Fielding. It does have some emerging de facto standards that make it that much more powerful. REST is directly tied to HTTP, which is good in many ways but may also hamper certain use cases and interactions.

SOAP, on the other hand, is steeped in standards and has relatively strict restraints. This does tend to make it easier to consume, as it’s predictable and generally lends more control to the developer. That control does come with a good deal of cost, however, in that SOAP is usually more verbose and expensive. That being said, SOAP’s standards make it perfect for high-security implementations, and for this reason, it has been used extensively in the enterprise space.

We should briefly mention that REST and SOAP are not the only API architectural paradigms in the API space. GraphQL has also seen much adoption as a query language to simplify the API interaction process. Other paradigms such as Webhooks, gRPC, and AMQP retain much mindshare, and we have previously compared them on the blog.

Conclusion

APIs power the internet, and in many respects, they are reflections of the underlying architecture and structure of the internet itself. Understanding what an API is — and how it functions — is key to understanding the nature behind the servers and the users that make up the web and its constituent pieces.

What do you think about this piece? Did we summarize this accurately and adequately? What do you think about non-SOAP and non-REST paradigms? Let us know below!