Back in 2015 when I was coding in PHP, I was not aware of the concept of APIs. We simply used to render the server side generated pages. With the advent of client side rendering frameworks in frontend like Angular & React, the use of APIs has become very common. Obviously the other benefit of APIs is that they can be used by the mobile applications like Android &iOS.
I had my first interaction with APIs when I was learning about Node.js back in 2016. At tis time too I was having limited knowledge about the API landscape and later in 2017, I got hold on GraphQL, WebSockets and gRPC as well. Currently gRPC is the hot cake in the world of APIs.
API Architecture
API architecture defines how requests are made, how responses are formatted, and how the API behaves under different conditions, rather than the specific implementation. It’s the guideline we set for clients and servers communicate, how data is represented, and how the API is organized to meet functional and non-functional requirements.
Today we will see the different API styles that we can use to communicate with web apps and mobile apps.
REST APIs
REST (REpresentational State Transfer) is an architectural style for designing networked applications. Introduced by Roy Fielding in 2000, REST emphasizes a stateless, client-server communication model, where resources are identified by URLs and manipulated using standard HTTP methods such as GET, POST, PUT, and DELETE.
The core principles of REST are:
- Statelessness: Each request contains all the information needed for the server to process it. The server does not store client context.
- Uniform Interface: Resources are exposed in a consistent way, making the API predictable.
- Resource-based: Every entity (user, product, order) is a resource identified by a URL.
- Cacheable Responses: Responses can be cached to improve performance.
- Layered System: The API architecture can have intermediary layers like load balancers, gateways, or proxies without altering functionality.
I have implemented a full fledged REST APIs with JWT using Node.js & MongoDB.
GraphQL
GraphQL, developed by Facebook in 2015, is a query language and runtime for APIs that enables clients to request exactly the data they need. Unlike REST, GraphQL uses a single endpoint and allows clients to define the shape and depth of the response.
Note: GraphQL is a POST call over HTTP.
GraphQL has pretty amazing feature:
- Client-driven queries where client specifies which fields it wants, reducing over-fetching or under-fetching.
- Unlike REST, there is no need for multiple endpoints for different resources, GraphQL has a single end-point.
- It is strongly typed schema of data and relationships.
- It also has real-time support through subscriptions where GraphQL can push updates to clients.
I have implementations of GraphQL gql and GraphQL & REST
WebSockets
WebSockets are a communication protocol providing full-duplex, bi-directional communication over a single TCP connection. Unlike REST or GraphQL, which are request-response based, WebSockets enable real-time communication where both client and server can send messages independently.
WebSockets are unique because:
- It supports persistent connection which remains open for continuous data transfer.
- It supports both client and server communication initiation i.e. bi-directional.
- It’s ideal for real-time applications due to minimal overhead compared to HTTP polling.
I did worked on a realtime chat app React & WebSocket
gRPC
gRPC, short for Google Remote Procedure Call, is an open-source, high-performance framework developed by Google. It enables client-server communication using remote procedure calls (RPCs) and is particularly suited for microservices, internal APIs, and applications requiring efficient, low-latency communication.
Note: gRPC uses Protocol Buffer for data serialization and deserialization over http/2
gRPC supports four types of communication:
- Unary RPC: One request followed by one response similar to REST API call.
- Server Streaming RPC: One request triggers a stream of responses.
- Client Streaming RPC: Multiple client messages sent before the server responds.
- Bidirectional Streaming RPC: Both client and server send multiple messages simultaneously, ideal for real-time applications.
I have worked on a gRPC poc but yet to push it to GitHub.
Making Decision
Now we know the different available choices we have, we should also understand how to choose the most suitable API style for our application.
Case I Simple CRUD
If we are dealing with simple CRUD application for available entities in our app them we can go with:
- REST - Best option, easy to begin and easy to scale
- GraphQL - Bit overkill but okay as the learning curve is not that high and works on
http - gRPC - This will be overkill as learning curve is high, development and deployment is complex. When ou have bunch of microservices, use this at high scale for inter-service communication.
Case II Complex Nested Requests
When we have dependent queries, the data is highly related and multiple API calls are required for rendering a particular UI, the best choice is to use GraphQL.
Case III Real-time Updates
When we need data instantly, the most suitable choices are:
- WebSockets as it has open TCP connection that allow bi-directional communication.
- GraphQL can also be used as it features subscriptions and can push data to the client.
- gRPC can help at high scale via the use of stream APIs
Case IV High Throughput
The best choice at extreme scale is to rely on gRPC as it uses http/2 and uses binary serialization protocol via ProtoBuf.
Case V Easy to implement & developer-friendly
The two choices in this segment are:
- REST
- GraphQL
Wrap Up
Choosing the right API architectural style is a critical decision that directly affects application performance, scalability, maintainability, and developer experience. To conclude we can quickly re-look that:
- REST offers simplicity, statelessness, and wide adoption, making it ideal for standard CRUD operations and public-facing APIs.
- GraphQL provides flexibility and precise data fetching, excelling in complex client scenarios and multi-resource queries.
- WebSockets enable real-time, bi-directional communication, essential for chat applications, live feeds, and collaborative platforms.
- gRPC delivers high-performance, strongly-typed, and streaming capabilities, particularly suitable for microservices and low-latency inter-service communication.
In the digital world, APIs are the bridges connecting apps, devices, and services. No single API style fits every application especially when it surpass a particular threshold. With time we must craft a hybrid path where performance, flexibility, and scalability coexist.
The right choice turns APIs into seamless, powerful experiences.
Keep Coding. Build, ship, repeat!