Skip to content

Brief

There are a number of patterns for designing APIs. These patterns have history, different requirements and create different experiences for users. These designs are somehow interconnected with each other, so we will see many places where they are very similar. Understanding them will help you in making a decision of which to use to address your specific issues.

REST

REST, short for Representational State Transfer, is an API protocol which was introduced in a 2000 dissertation by Roy Fielding, whose goal was to solve some of the shortcomings of SOAP.

Like SOAP, REST relies on a standard transport protocol, HTTP, to exchange information between different applications or services. However, REST is more flexible in that it supports a variety of data formats, rather than requiring XML. JSON, which is arguably easier to read and write than XML, is the format that many developers use for REST APIs. REST APIs can also offer better performance than SOAP because they can cache information.

According to a 2017 report by Cloud Elements, REST APIs accounted for 83 percent of all API types in that year (although the report did not study all API protocols).

REST is a very good standard for a wide variety of APIs, but there are other API design styles for more nuanced scenarios.

REST is truly a “web services” API putting it on the opposite side of SOAP (probably why you will see a dozen comparisons on them without looking too much). REST APIs are based on URIs (uniform resource identifier) and the HTTP protocol. REST APIs can exchange data in either JSON or XML format, although many REST APIs send data as JSON.

When building a system with minimal security considerations but strong speed requirements, REST is an excellent choice. RESTful APIs have fewer security requirements, boost browser client compatibility, discoverability, data health, and scalability—things that really apply to web services.

SOAP

SOAP, the oldest web-focused API protocol that remains in widespread use. Introduced in the late 1990s, SOAP was one of the first protocols designed to allow different applications or services to share resources in a systematic way using network connections.

Technically speaking, SOAP is an example of a Remote Procedural Call, or RPC. RPC is a broad category of approaches for allowing different computers to communicate with each other. It has existed since the 1970s, and extends far beyond web applications.

SOAP stands for Simple Object Access Protocol. Some developers might take issue with the notion that SOAP is “simple,” because using a SOAP protocol requires a fair bit of work. You have to create XML documents to make calls, and the XML formatting that SOAP requires isn’t exactly intuitive. This not only makes call implementation difficult, but also makes problems hard to debug, because debugging requires parsing through long strings of complex data.

On the other hand, SOAP relies on standard protocols, especially HTTP and SMTP. That means that you can use SOAP in virtually every type of environment, because these protocols are available on all operating systems.

SOAP can be argued to be a communication protocol rather than an API architecture/pattern because it defines its set of communication rules and security protocols and all of that. SOAP APIs carry more overhead than their counterparts, but they come with their own benefits. For one, they provide more security when designing large scale enterprise applications.

Many of the reasons to pick SOAP include features around security, transactions, and ACID (atomicity, consistency, isolation, durability) compliance, all of which rarely apply to web services scenarios, hence its stronger appeal to enterprise scale applications.

JSON-RPC

While REST supports RPC data structures, it’s not the only API protocol in this category. If you like JSON, you may prefer instead to use JSON-RPC, a protocol introduced in the mid-2000s.

Compared to REST and SOAP, JSON-RPC is relatively narrow in scope. It supports a small set of commands, and does not offer as much flexibility as a protocol like REST with regard to exactly how you implement it. However, if you like simplicity and have a straightforward use case that falls with JSON-RPC’s scope, it can be a better solution than REST.

gRPC

gRPC is an open source API that also falls within the category of RPC. Unlike SOAP, however, gRPC is much newer, having been released publicly by Google in 2015.

Like REST and SOAP, gRPC uses HTTP as its transport layer. Unlike these other API protocols, however, gRPC allows developers to define any kind of function calls that they want, rather than having to choose from predefined options (like GET and PUT in the case of REST).

Another important advantage of gRPC, at least for many use cases, is that when you make a call to a remote system using gRPC, the call appears to both the sender and the receiver as if it were a local call, rather than a remote one executed over the network. This simulation avoids much of the coding complexity that you’d otherwise have to contend with in order for an application to handle a remote call.

The ability of gRPC to simplify otherwise complex remote calls has helped make it popular in the context of building APIs for microservices or Docker-based applications, which entail massive numbers of remote calls.

GraphQL

In a way, GraphQL is to Facebook what gRPC is to Google: It’s an API protocol that was developed internally by Facebook in 2013, then released publicly in 2015. As such, GraphQL, which is officially defined as a query language, also represents an effort to overcome some of the limitations or inefficiencies of REST.

One of the key differences between REST and GraphQL is that GraphQL lets clients structure data however they want when issuing calls to a server. This flexibility improves efficiency because it means that clients can optimize the data they request, rather than having to request and receive data in whichever prepackaged form the server makes available (which could require receiving more data than the client actually needs, or receiving it in a format that is difficult to use). With GraphQL, the clients can get exactly what they want, without having to worry about transforming the data locally after they receive it.

Picking the right API Paradigm

To oversimplify things a bit, it's reasonably fair to say that all APIs conform to a paradigm: "RPC", "REST", or "query language". These are general approaches to building APIs, but not a specific tool or specification. They are merely a concept, not a tangible thing.

Implementations are something you can actually download, install, and use to build an API, that conforms to whatever rules the implementors picked, from whichever paradigms they wanted to use at the time.

Specifications (standard, recommendation, etc.) are often drafted up by various working groups, to help implementations share functionality in the same way. An API and a client in different languages can work together perfectly if they're all following the specification correctly.

For example:

  • SOAP is a W3C recommendation, following the RPC paradigm, with implementations like gSOAP
  • gRPC is a implementation, following the RPC paradigm, which has no standard or specification by any working group, but authors Goolge Inc. did document the protocol
  • REST is a paradigm, which has never been turned into a specification, and has no official implementations, but building a REST API is usually just a case of picking appropriate standards and tooling

Full sized image

Swagger

Swagger allows you to describe the structure of your APIs so that machines can read them. The ability of APIs to describe their own structure is the root of all awesomeness in Swagger. Why is it so great? Well,by reading your API’s structure, we can automatically build beautiful and interactive API documentation. We can also automatically generate client libraries for your API in many languages and explore other possibilities like automated testing. Swagger does this by asking your API to return a YAML or JSON that contains a detailed description of your entire API. This file is essentially a resource listing of your API which adheres to OpenAPI Specification. The specification asks you to include information like:

  • What are all the operations that your API supports?
  • What are your API’s parameters and what does it return?
  • Does your API need some authorization?
  • And even fun things like terms, contact information and license to use the API.

You can write a Swagger spec for your API manually, or have it generated automatically from annotations in your source code. Check swagger.io/open-source-integrations for a list of tools that let you generate Swagger from code.

Further reading