API architectural styles

An overview of the most popular API architectural styles: SOAP, REST, GraphQL, Webhook, Websocket, and gRPC.

Hi Friends,

Welcome to the 101st issue of the Polymathic Engineer. This week, we talk about API architectural styles.

APIs are ways for web applications to talk to each other and share data. But there are different ways to design and build APIs. Knowing those APIs architectures and their differences is necessary to pick the best one for a system.

Here, we will review the most popular ones:

• SOAP

• REST

• GraphQL

• Webhook

• Websocket

• gRPC

---

Project-based learning is the best way to develop technical skills. CodeCrafters is an excellent platform for practicing exciting projects, such as building your version of Redis, Kafka, HTTP server, SQLLite, or Git from scratch.

Sign up, and become a better software engineer.

---

SOAP (Simple Object Access Protocol)

SOAP is one of the first and most well-known API designs for web services. It sends messages in XML format and can work with different protocols, though HTTP is the most popular one.

The structure of the messages is strongly defined using the Web Services Description Language (WSDL). This makes sure that the data exchanges and the handling of errors through SOAP faults are consistent.

The use of SOAP is prevalent in enterprise environments or legacy systems, especially in industries like finance or healthcare, where strict data contracts and security measures are crucial.

The main downside of SOAP is its verbose XML format which leads to larger message sizes and potential performance issues. SOAP also has a steeper learning curve and is less flexible compared to modern alternatives like REST or GraphQL.

REST (Representational State Transfer)

REST is the most used API architecture for modern web services. They use URIs to find resources (both data and functionalities) and standard HTTP methods to get to them.

GET, POST, PUT, DELETE correspond to read, create, update, and delete operations. They typically use JSON for data formatting, though XML is also supported.

A key feature of REST APIs is stateless communication. Each request contains all the information it needs and servers don't have to keep session information between calls.

This makes REST APIs very flexible and scalable. In addition, it makes caching work better, and the whole creation process more straightforward.

However, REST is not without limitations. It has limited support for complex queries and operations, which can make it need many requests and get too much or too little data. Also, it does not always handle errors or exceptions consistently as it uses HTTP status codes, which are not always clear or correct.

Despite these drawbacks, REST remains the most common choice for public APIs and web services that prioritize simplicity and scalability.

GraphQL

GraphQL is a query language for APIs that allows clients to request exactly the data they need.

Unlike REST, where the server determines the structure of the response, GraphQL puts this control in the hands of the client. This approach effectively addresses the over-fetching and under-fetching data issues that can occur with REST APIs.

GraphQL APIs typically have a single endpoint. Clients send queries describing the exact data format they need, and the server sends back just that info, nothing else.

This efficiency in data transfer cut down the amount of data sent over the network, improving the performance. GraphQL also supports updates through subscriptions, allowing clients to receive immediate updates when data changes on the server.

Even if GraphQL is very flexible, it comes with more complexity on the server side.

It is are more challenging to use and understand, as it requires learning a new syntax and logic. Also, because each GraphQL query might be different, caching is harder to do than with REST.

Even with these problems, GraphQL is popular in situations where clients need exact control over data retrieval. This is especially true in cases when bandwidth efficiency is very important or in complex web apps where each view needs different amounts of data.

Webhooks

Webhooks are a mechanism that lets servers notify other systems in real time when specific events occur. Unlike other API styles where clients repeatedly request data, Webhooks use a push mechanism, allowing servers to send data proactively.

The basic concept is simple. The client sets up a URL to receive notifications. The server sends an HTTP POST request to this URL when an event happens.

Since Webhooks eliminate the need for constant polling, they are efficient for all the scenarios where real-time updates are crucial, such as payment notifications.

However, Webhooks have their challenges. First of all, clients need to have a publicly accessible endpoint to receive notifications, which can be a security concern. Second, there is also no built-in way to check message delivery, so it is up to the developer to add retry logic and deal with failed deliveries.

WebSocket

WebSocket is a protocol that enables real-time, bidirectional communication. Unlike stateless HTTP connections, which go through request-response cycles, WebSocket keeps a persistent connection.

The protocol starts with an HTTP handshake. After that, the connection becomes a full-duplex WebSocket, where clients and servers can send messages anytime without the overhead of establishing a new connection.

Thanks to this, WebSocket works great in situations where small amounts of data are sent often, like live chat apps, online games, and trade platforms.

However, older browsers or network proxies may not fully support WebSocket, so there needs to be a way to fall back.

gRPC

gRPC is a framework that uses HTTP/2 for transport and Protocol Buffers to convert data into a binary format. Protocol buffers set the rules for how the data is structured and how the service methods work.

These definitions are then used to generate code for the client and server. This speeds up the development process and ensures type safety across different languages. gRPC supports four service methods: request-response, server streaming, client streaming, and bidirectional streaming.

The gRPC's main advantage is its performance. Since messages are compact and efficient, they are often used in microservices systems. As a downside, gRPC has limited browser support, so web applications require a proxy.

Interesting Read

Some interesting articles I read this week:

• No matter what the books say, nobody likes making 20 requests to render a page. by

  Raul Junco

• 8 Must-Know Strategies to Build Scalable Systems by

  Saurabh Dashora

• 3 main soft skills a Tech Lead needs to develop by

  Gregor Ojstersek