Architectural Styles for APIs: SOAP, REST and RPC

In general, an architectural style is a large-scale, predefined solution structure. Using an architectural styles helps us to build the system quicker than building everything from scratch. Architectural styles are similar to patterns, but provide a solution for a larger challenge.

In this blog we study several architectural styles for communication in distributed systems. The REST style (Representational State Transfer), the REST-like style, the RPC style (Remote Procedure Call), the SOAP style and GraphQL. We compare the approaches, show advantages and disadvantages, commonalities and differences.

APIs can basically be realized using any of these styles. How do we know, whether a particular architectural style is appropriate for a given API?

When realizing a new API, an appropriate API philosophy should be chosen, such as GraphQL, REST, SOAP or RPC.

So which should you choose for your cool new API?

Once the bigger-picture, architectural design decisions are nailed, frontend design decisions can be handled. These design decisions should be documented by refining and updating the API description. The API description thus becomes an evolving, single source of truth about the current state of the system.

REST Style

REST (Representational State Transfer) is an architectural style for services, and as such it defines a set of architectural constraints and agreements. A service, which complies with the REST constraints, is said to be RESTful.

REST is designed to make optimal use of an HTTP-based infrastructure and due to the success of the web, HTTP-based infrastructure, such as servers, caches and proxies, are widely available. The web, which is based on HTTP, provides some proof for an architecture that not only scales extremely well but also has longevity. The basic idea of REST is to transfer the ideas that worked well for the web and apply them to web services.

HATEOAS is an abbreviation for Hypermedia As The Engine Of Application State. HATEOAS is the aspect of REST, which allows for dynamic architectures. It allows clients to explore any API without any a-priori knowledge of data formats or of the API itself.

REST-like APIs

There is a large group of APIs, which claim to follow the REST Style, but actually, they don’t. They only implement some elements of REST, but at its core, they are RPC APIs.

Johnson Maturity Index may be helpful

RPC Style

RPC is an abbreviation for Remote Procedure Call. RPC is an architectural style for distributed systems. It has been around since the 1980s. Today the most widely used RPC styles are JSON-RPC and XML-RPC. Even SOAP can be considered to follow an RPC architectural style.

The central concept in RPC is the procedure. The procedures do not need to run on the local machine, but they can run on a remote machine within the distributed system. When using an RPC framework, calling a remote procedure should be as simple as calling a local procedure.

SOAP Style

SOAP follows the RPC style (see previous section) and exposes procedures as central concepts (e.g. getCustomer). It is standardized by the W3C and is the most widely used protocol for web services. SOAP style architectures are in widespread use, however, typically only for company internal use or for services called by trusted partners.

GraphQL Style

For a long time, REST was thought to be the only appropriate tool for building modern APIs. But in recent years, another tool was added to the toolbox, when Facebook published GraphQL, the philosophy, and framework powering its popular API. More and more tech companies tried GraphQL and adopted it as one of their philosophies for API design. Some built a GraphQL API next to their existing REST API, some replaced their REST API with GraphQL, and even others have ignored the GraphQL trend to focus single-mindedly on their REST API.

But, not only the tech companies are divided. Following the discussions around REST and GraphQL, there seem to be two camps of gurus leading very emotional discussions: “always use the hammer,” one camp proclaims. “NO, always use the screwdriver,” the other camp insists. And for the rest of us? Unfortunately, this situation is confusing, leading to paralysis and indecision about API design.

The intention of the Book on REST & GraphQL is to clear up the confusion and enable you to make your own decision, the decision that is right for your API. By having the necessary criteria for comparison and general properties, strengths, and weaknesses of the approach, you can choose if the hammer or the screwdriver is better suited for your API project.

Conclusion

APIs can basically be realized using any of these styles. How do we know, whether a particular architectural style is appropriate for a given API? The resulting API exposes many of the previously stated desirable properties.

Most commonly, APIs are realized using REST over HTTP. This is why one can assume in practice that APIs are realized with the REST style.

When should I use which style? Check the API Architecture Book.

Originally published at API-University.