API vs. Web Service

Some of the most confusing questions I usually have are "What are the differences between APIs and Webservices"? Are they really different or related? Why are REST web services called APIs?

In the following post, I will take you on a brief journey through the history of API to answer these questions, but first, we need to understand what API means.

What Is API?

API stands for Application Programming Interface and as its name implies, it is an interface that allows any piece of code to interact programmatically with another piece of code. The piece of code can be a library, component, resource, or even a different application.

The APIs can be either an internal API that allows native interactions between different parts of the same application codebase, such as calling another class or library within the same deployment. On the other hand, the external API allows remote interactions, such as calling another component for the same application deployed in a different environment (for distributed applications) or even calling a different application. The external interactions require network communication supported by a network protocol (such as HTTP, JMS, TCP, etc.).

Well-designed APIs (internal or external), can increase the solution reusability, hide implementation complexity, and decrease the clients' dependencies on the implementation which allows the implementation to evolve Independently without affecting the clients.

In the below diagram, the java interface called "SearchI" is considered an API that allows the client code to perform the search functionality without getting coupled to the underlying implementation:

In the above diagram, if we decided to change the BinarySearch class with LinearSearch, the client will not be affected as long as the interface specifications are not changed.

API Main Components

API usually consists of three components:

1. The Activities This is the set of actions and operations provided by the interface and performed by the underlying implementation. An example of internal API activities is the list of methods defined in the java interface. An example of external API activities is the list of operations defined in a webservice WSDL
2. The Data Model describes the entities and attributes of the activities' input and output. An example of the data model is the CompanyProfile entity that needs to be passed to the API to perform a specific activity.
3. The Data Format describes the shape of the data. For internal APIs, the data format can be as per the native programming language formats. For external APIs, the data format can be SOAP, JSON, or even serialized binary format such as gRPC.

API Generations

API history can be divided into four main generations as illustrated in the below timeline:

As per the above diagram, the third generation of the APIs was the web API, which had two main styles: REST-based WS and SOAP-based WS. In this generation, the APIs invocations have been running over the internet using mainly HTTP protocol.

In the following diagram, we will dig deeper into the history of the web API generation to see how the Web APIs have evolved over time.

The Right Question

It is clear now that the right question should be: What is the relationship between web service and API? And as we have seen, web service is just one of the API types.

By now, you may wonder why the REST web services are called APIs? The most likely reason was the hate for the SOAP web services by the REST adaptors, who decided to give this style a new name that has no “web services” and obviously no “SOAP” and eventually, the decision was to name it “REST API." By that time it became just “API” for simplicity, which caused a lot of confusion as it was difficult to know if we were talking about the API in general or the REST WS in specific.

Accordingly, and as a piece of general advice, make sure when you discuss APIs that the listener is aware of which type of APIs you are talking about.

Don't forget to Subscribe to get notifications for my new articles.