There are lots of REST and API terminologies we come across in software development. For example REST, RESTful, APIs, Web APIs, Web Services, etc. just to name a few. It’s always confusing for most of the software developers and architects, and they start using these terminologies in a wrong context sometimes. Let’s clear the confusion between these various terminologies used very frequently nowadays in software development.
REST (REpresentational State Transfer)
REST is just a software architecture style which contains set of rules or standards or guidelines we can say. It uses a subset of HTTP (stateless protocol). REST just is a guiding principle how to use URLs and the HTTP protocol to structure an API. REST is an API type. REST is a design pattern for APIs.
In the REST style, clients send requests to retrieve or modify resources, and servers send responses to these requests. REST requires that a client make a request to the server in order to retrieve or modify data on the server. The request consists of an HTTP verb (remember REST uses a subset of HTTP), a header, a path to the source, and an optional message body.
REST uses following HTTP verbs for CRUD (Create, Read, Update, and Delete) operations
GET – Read
POST – Create
PUT – Update
DELETE – Delete
API (Application Programming Interface)
An API is a set of defined rules or specifications that explain how computers or applications communicate with one another. It sit between an application and the web server, acting as an intermediary layer that processes data transfer between systems.
API is a contract (uniform interface) between a consumer and a service provider who exposes the API to the external world so that it’s services consumed uniformly. API is best to perform a quick action and receive an immediate response. API works in a request-response manner, which is short-lived communication. There are other alternatives of APIs which suites better in different scenarios.
Types of API Protocols
SOAP (Simple Object Access Protocol)
XML-RPC
JSON-RPC
REST
WebSockets
WebSockets is what you need in the real-time communication. It allows a persistent and bi-directional communication between the consumer and the service provider. API is not capable to handle persistent and bi-directional communication. WebSockets allows a full-duplex communication channel so that the service providers can send messages at any time.
WebSockets is having its own challenges. For example, keeping the connection open all the time increases resource consumption, power usage (mobile devices), and makes it difficult to scale.
WebHooks
WebHooks is resolving the challenges facing by the WebSockets. It provides a disconnected mechanism to receive a response which is originated from the service provider. Tehnically speaking, the consumer registers the WebHook (callback URL) into the service provider, and the URL will act as the place to receive response (data) from WebHook. WebHooks are mostly used to communicate between different servers or backend-processes.
In the interest to keep the article short and relevant, I’m not covering other real-time communication options here for example short polling, long polling, server-sent event (SSE) or EventSource, WebRTC (Web Real-Time Communication), SignalR, AJAX polling, Comet, etc. You can obviously Google these terminologies and deep dive into it.
RESTful
RESTful is not any terminology, but a buzzword. It’s used frequently for those APIs which comply with the REST specifications. There is another open source initiative OpenAPI Specifications (OAS) (formerly known as Swagger) to standardize REST APIs.
SOAP (Simple Object Access Protocol)
SOAP is an API protocol. It focuses on exposing pieces of application logic (not data) as services. It exposes operations. SOAP is focused on accessing named operations, each implement some business logic through different interfaces. SOAP is commonly referred as a “Web Service” which is wrong, but we can call it a SOAP service. That’s the reason Microsoft .NET Web Service which deals with SOAP request and response is called “Web Service”.
Its common to refer a service or API based on what it deals with. For example, if it deals with SOAP then it normally called SOAP service or SOAP API and similarly if it deals with JSON then it is called JSON service or JSON API.
Web Services
Web Service is SOAP based service that returns data as an XML and only supports HTTP protocol. In simple sense, it’s a type of API only with limited features. We can say it’s type of API only with some limitations. Web services stick to SOAP and WSDL (Web Services Description Language).
A web service is a collection of open protocols and standards used for exchanging data between applications or systems, so don’t confuse it with the Microsoft framework offerings “Web Service”. What Microsoft offers in “Web Service” is just a technology to build the web services.
Web APIs
Web API is an open source framework for writing HTTP(s) APIs. It can be RESTful (if it follows REST specifications) or not. It is a concept not a technology, so developers can build Web APIs using vast array of technologies like .NET, Java, etc.
Web API implements protocol specification so it also incorporates concepts like caching, URIs, versioning, request/response headers, and various content formats in it.
RPC (Remote Procedure Call) and gRPC
An RPC is a protocol for an interprocess communication used for the client server based applications. In a layman term, it allows you to call a function that sits on a different server. Based on the RPC protocol, Google has introduced gRPC using protocol buffers which can be used to develop APIs as an alternative to the RESTful APIs. However, it does not suits for all the scenarios at the moment. You can read more about gRPC here.
The gRPC makes use of HTTP/2 while compatible with older HTTP versions. It takes full advantage of HTTP/2 capabilities like binary data transport, multiplexing support, bi-directional full duplex communication, built-in streaming enabling, header compression, etc. We can obviously implement RESTful APIs using HTTP/2, but it can not take advantage of HTTP/2 because of its architecture and style.
GraphQL
GraphQL is an open spec for a flexible API layer. Put GraphQL over your existing backends to build products faster than ever before. GraphQL is an open-source data query and manipulation language for APIs, and a runtime for fulfilling queries with existing data. Simply put, GraphQL is a query language that lets you write queries using an object structure rather than a text string.
GraphQL is very useful in some scenarios for example Bounded Context in DDD (Domain Driven Design) pattern and BFF (Backend For-Frontend) in Cloud/Microservice design patterns.
Microservices
Microservice is an architecture and organizational style of software development, that structures an application as a collection of loosely coupled services. It’s the most popular approach as a cloud native architectural approach. In Microservice style, each service is given single task and clear boundaries.
It’s evolved from the SOA (Service Oriented Architecture). As a first stage of evolution, monolith application broken down into SOA. As a second stage of evolution it’s further broken down into micro-services. Most popular approach to build microservices is using RESTful APIs.
SOAP vs REST vs JSON
SOAP is a standard protocol to send messages using other protocols like HTTP and SMTP. REST is not a protocol but an architectural style. JSON is just a messaging form for request and response like HTML, XML or plain text.
REST was created to address the problems of SOAP. So REST is having more flexible architecture because it consists of loose guidelines so that the developers can implement the recommendations in their own way.
SOAP is using XML for the request and response messaging. REST allows multiple formats like HTML, XML, YAML, plain text, and JSON. But most popular messaging format in REST is JSON, because it’s easy-to-parse and lightweight data-interchange format.
SOAP does not support caching. REST only supports HTTP protocol, while SOAP supports HTTP, SMTP, UDP, and others. So SOAP is still popular for enterprise apps with high security requirement in financial services like PayPal API.