*This is a continuation of a series of articles in which I briefly cover the main points of a specific topic in system architecture design. The first article can be read here *and the full guide you can find on my github.

API architecture refers to the set of rules, protocols, and tools that dictate how software components should interact. The architecture of an API is not just about facilitating communication; it's also about ensuring that this communication is efficient, secure, and scalable.

A well-designed API architecture can significantly enhance the performance of a system, while a poorly designed one can lead to bottlenecks, security vulnerabilities, and maintenance nightmares.

Different Styles of API Architecture

The most common API design styles:

  1. REST (Representational State Transfer) is the most used style that uses standard methods and HTTP protocols. It's based on principles like statelessness, client-server architecture, and cacheability. It's often used between front-end clients and back-end services.

  2. GraphQL is a query language for APIs. Unlike REST, which exposes a fixed set of endpoints for each resource, GraphQL allows clients to request exactly the data they need, reducing over-fetching.

  3. WebSocket is a protocol allowing two-way communication over TCP. Clients use web sockets to get real-time updates from back-end systems.

  4. Webhook is a mechanism that allows one system to notify another system about specific events in real-time. It is a user-defined HTTP callback.

  5. RPC (gRPC) is a protocol that one service can use to request a procedure/method from a service located on another computer in a network. Usually, It's designed for low-latency, high-speed communication.

  6. SOAP is a protocol for exchanging structured information to implement web services. It relies on XML and is known for its robustness and security features, currently considered a legacy protocol.

Let's look at each protocol separately with all their pros, cons, and use cases.

REST

REST is an architectural style that uses standard conventions and protocols, making it easy to understand and implement. Its stateless nature and use of standard HTTP methods make it a popular choice for building web-based APIs.

While REST has been the de facto standard for building APIs for a long time, other styles like GraphQL have emerged, offering different paradigms for querying and manipulating data.

Format: XML, JSON, HTML, plain text

Transport protocol: HTTP/HTTPS

Key Concepts and Characteristics

Use Cases

Example

Request

GET “/user/42”

Response

{
    "id": 42,
    "name": "Alex",
	"links": {
        "role": "/user/42/role"
    }
}

GraphQL

GraphQL offers a more flexible, robust, and efficient approach to building APIs, especially in complex systems or when the frontend needs high flexibility. It shifts some of the responsibility from the server to the client, allowing the client to specify its data requirements.

While it's not a replacement for REST in all scenarios, it offers a compelling alternative in many situations, particularly as applications become more networked and distributed.

Format: JSON

Transport protocol: HTTP/HTTPS

Key Concepts and Characteristics

Use Cases

Example

Request

GET “/graphql?query=user(id:42){ name role { id name } }”

Response

{
    "data": {
        "user": {
            "id": 42,
            "name": "Alex",
            "role": {
                "id": 1,
                "name": "admin"
            }
        }
    }
}

WebSocket

WebSockets provide a full-duplex communication channel over a single, long-lived connection, allowing real-time data exchange between a client and a server. This makes it ideal for interactive and high-performance web applications.

Format: Binary

Transport protocol: TCP

Key Concepts and Characteristics

Use Cases

Example

Request

GET “ws://site:8181”

Response

HTTP/1.1 101 Switching Protocols

Webhook

Webhook is a user-defined HTTP callback triggered by specific web application events, allowing real-time data updates and integrations between different systems.

Format: XML, JSON, plain text

Transport protocol: HTTP/HTTPS

Key Concepts and Characteristics

Use Cases

Example

Request

GET “https://external-site/webhooks?url=http://site/service-h/api&name=name”

Response

{
  "webhook_id": 12
}

RPC and gRPC

RPC (Remote Procedure Call) is a protocol that allows a program to execute a procedure or subroutine in another address space, enabling seamless communication and data exchange between distributed systems.

gRPC (Google RPC) is a modern, open-source framework built on top of RPC that uses HTTP/2 for transport and Protocol Buffers as the interface description language, providing features like authentication, load balancing, and more to facilitate efficient and robust communication between microservices.

RPC

Format: JSON, XML, Protobuf, Thrift, FlatBuffers

Transport protocol: Various

Key Concepts and Characteristics

Use Cases

Example

Request

{
    "method": "addUser",
    "params": [
        "Alex"
    ]
}

Response

{    
    "id": 42,
    "name": "Alex",
	"error": null
}

gRPC

Format: Protobuf

Transport protocol: HTTP/2

Key Concepts and Characteristics

Use Cases

Example

message User {
  int id = 1
  string name = 2
}

service UserService {
  rpc AddUser(User) returns (User);
}

SOAP

SOAP, which stands for Simple Object Access Protocol, is a protocol for exchanging structured information to implement web services in computer networks. It's an XML-based protocol that allows programs running on disparate operating systems to communicate with each other.

Format: XML

Transport protocol: HTTP/HTTPS, JMS, SMTP, and more

Key Concepts and Characteristics

Use Cases

Example

Request

<?xml version="1.0"?>
<soap:Envelope>
	<soap:Body>
		<m:AddUserRequest>
			<m:Name>Alex</m:Name>
		</m:AddUserRequest>
	</soap:Body>
</soap:Envelope>

Response

<?xml version="1.0"?>
<soap:Envelope>
	<soap:Body>
		<m:AddUserResponse>
			<m:Id>42</m:Id>
			<m:Name>Alex</m:Name>
		</m:AddUserResponse>
	</soap:Body>
</soap:Envelope>

Conclusion

The landscape of API architecture styles is diverse, offering various approaches like REST, SOAP, RPC, and more, each with unique strengths and use cases, enabling developers to choose the most suitable paradigm for building scalable, efficient, and robust integrations between different software components and systems.