Comparison of API Architectural Styles

API architectural style foundations

APIs’ commercial usage has grown exponentially with web and mobile development. When designing an API, developers typically choose an architectural style first. Over 90% of developers have adopted this styleSimpson, J. 2022. "20 Impressive API Economy Statistics | Nordic APIs |." Nordic APIs. February 9, 2022. https://nordicapis.com/20-impressive-api-economy-statistics/ (REST), yet after analyzing technical requirements, a different approach may prove superior.

An architectural style defines the rules and protocols for creating APIs: large-scale, standardized templates that are often faster and more efficient than building from scratch. Like design patterns, they provide structure on top of which we construct an API. This decision has long-lasting effects across the entire development timeline. Constraints such as API consumers, business preferences, and the API’s purpose all factor in. Once you settle on a style, changing it later becomes costly.

Characteristics of an architectural style

Each style serves as a template with constraints, so we evaluate which characteristics suit our design problem. Desirable properties to consider include:

Each architectural style implements these properties to varying degrees. There is no universally “best” style; developers define nonnegotiables by selecting essential properties. Trade-offs are inherent: increasing performance may negatively impact scalability (for example, adding more parallel servers can reduce latency, but it increases compute costs). In design, it is always about trading one aspect for another.

Three core API architectural styles

REST

Representational state transfer (REST) is the most popular style. In the industry, REST API practices rely heavily on HTTP and are considered easy to understand, use, and manage. Its familiarity and simplicity are its greatest strengths, though it may struggle in event-driven environments. It excels when scalability and modifiability are desired characteristics.

RPC

The remote procedure call (RPC) is one of the earliest API approaches (1980s) and was commonly used for database access via JSON and XML. Its core concept is the procedure, which can be executed remotely. The concept is detailed in the Remote Procedure Calls (RPC) lesson. Two RPC-based architectural styles exist:

• gRPC: Google’s general-purpose RPC framework (2015) implements RPC-based APIs using protocol buffers for serialization. It reduces latency through compression and is actively maintained.

• SOAP: Simple Object Access Protocol (1999, Microsoft) uses XML with strict rules for encoding and structuring messages and handling requests. It has built-in error handling, but its inflexible nature produces large requests with significant overhead. Few major services still use SOAP, and it is largely considered obsolete.

GraphQL

GraphQL is a query language specification for APIs developed by Facebook in 2012 to address REST’s shortcomings. Applications like GitHub and Yelp have adopted GraphQL over REST, despite its relatively recent release.

With these three styles established, the following sections expand on each: REST’s architectural constraints and best practices, GraphQL’s query-based approach, and gRPC’s high-performance framework. A comparative analysis follows to guide the final architectural decision.

REST: origins and architectural constraints

In December 1990, Tim Berners-Lee launched the World Wide Web project. After it opened to the public, the number of users grew to 40 million within five yearsMasse, Mark. REST API Design Rulebook. O’Reilly Media, 2011., threatening to outgrow the internet infrastructure’s capacity. This forced software architects to design an efficient web architecture for flexibility, performance, and scalability. REST was the proposed solution.

Note: "All design decisions at the architectural level should be made within the context of the functional, behavioral, and social requirements of the system being designed, which is a principle that applies equally to both software architecture and the traditional field of building architecture." — Roy Fielding (the author of the Ph.D. dissertation that originally presented REST)

Representational state transfer (REST)

REST is a web architectural style proposed by Roy Fielding in 2000Roy Fielding originally presented REST in his Ph.D. dissertation. [R. T. Fielding, Architectural Styles and the Design of Network-based Software Architectures. University of California, Irvine, 2000.] to solve the web’s scalability problem. Fielding identified key constraints that collectively form the web’s architectural style and serve as the backbone for designing REST APIsAn API that follows the REST constraints is called a REST or RESTful API..

These constraints are:

• Client-server

• Cache

• Stateless

• Uniform interface

• Layered system

• Code-on-demand

Client-server

This is the most commonly used style for network-based applications. A server componentIn an architectural style, clients, servers, and other intermediate entities are considered components. listens for requests, processes them, and returns responses to the client via the internet (connector).

Separation of concernsIn computer science, separation of concerns is a design principle for separating a computer program into distinct sections. [https://en.wikipedia.org] is the core principle: the server is simplified through functional separation, while all user interface features are consolidated into the client component. Both evolve independently as long as the interface remains stable.

Cache

A cache is an intermediate component between the client and the server that stores responses to earlier requests. These cached responses serve equivalent or identical"Equivalent" refers to the kind of HTTP methods we are using, while "identical" refers to similarity with respect to the arguments passed to those methods. requests instead of routing them to the server, improving network efficiency and perceived performance.

Note: Response data can be cached on the client side and used for similar or equivalent requests.

Response data must be explicitly or implicitly marked as cacheable or non-cacheable. The major trade-off is that stale cached data can reduce reliability and consistency if it diverges significantly from the server's current state.

Stateless

No session state resides on the server; each client request must contain all the information necessary for processing.

Note: The server should not store any data from previous requests.

The stateless constraint improves:

• Reliability because server failures don't disrupt client-side activity or lose prior request data.

• Scalability because resources are freed immediately after processing, enabling the server to handle more concurrent requests.

• Visibility because a monitoring system can determine a request's full nature from a single request, without needing extra context.

The trade-off is that repeating data across successive requests (since nothing persists on the server) can reduce network performance.

Uniform interface