I have 20+ years of experience in software development and software architecture.
The most confusing questions I usually get are: What is the API and what is the web service? What are the differences? Are they really different? Why are REST (representational state transfer) web services called API?
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 is an abbreviation for Application Programming Interface and as the name implies, it is an interface that allows a piece of code to interact programmatically with another piece of code. The piece of code can be library, resource, component, or even a different system or 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 on a different environment (for distributed applications) or even calling a totally different application. The external interactions require a network communication supported by a network protocol (such as HTTP, JMS, TCP, etc.).
If the API (internal or external) is designed carefully, it can increase the solution reusability, hide implementation complexity, and decrease the clients dependencies on the internal implementation, which is supposed to enhance the overall maintainability for the solution.
In the below diagram, the interface called “SortI” is an example of a native internal API that allows the client code to perform the sorting functionality without direct coupling with the underling implementation.
In the above diagram, if we decided to change the BubbleSort implementation with HeapSort, the client will not be affected considering that the interface is not changed.
API Main Components
API consists of three main components:
- Activities: This is the set of actions and operations provided by the interface. For example, the methods defined in the java interface or the operations defined in the WSDL file
- Data model: The data structure for the operations input or output. For example, the input parameters and the return value structure for the java interface operations or the schemas of the WSDL input and output messages.
- Data format: This is the format that defines the data shape. For example, binary format for internal APIs and SOAP format for SOAP-based WS.
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 where remote API calls have been running over the internet using mainly HTTP protocol.
In the following diagram, we will dig deeper into the history of the web generation to see how the Web API has evolved over the 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 as “REST API." In 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 general piece of advice, make sure when you have a discussion about the APIs that the listener is aware of which type of APIs you are talking about.
This content is accurate and true to the best of the author’s knowledge and is not meant to substitute for formal and individualized advice from a qualified professional.
© 2022 Haitham Raik