RESTful APIs using JSON on the HTTP protocol is by far the most popular approach to creating web APIs.

The three key aspects for these different types:

  • Design Philosophy/Pattern (e.g. RESTful vs GraphQL)
  • Communication Protocol (e.g. HTTP vs WebSockets)
  • Encoding (e.g. Human readable text such as JSON vs Binary formats like ProtoBuf)

Often, these three different aspects can be mixed together. For example, you can use RESTful API over WebSockets but using a Binary Protocol like MessagePack.

GraphQL

Comparing GraphQL and RESTful

Generally, there are pro and cons, but both have their places. GraphQL and REST can work together as well. Choose the right tools for your application. If your application’s data model have a lot of complex entities that reference each other (like Facebook), GraphQL make sense. But if you have only few data entities, and the additional complexity of implementing GraphQL may not worth it.

Resources for GraphQL

Tutorial for GraphQL usually are language or platform specific. Please check out the language specific api-guide.

JSON vs XML

For RESTful APIs, the format used for transfer data is almost always JSON. But JSON isn’t the only way to encode data. XML can be used also. Even if we default to JSON, it may worth a while to understand the differences.

Background on XML

Background on JSON

Pros and Cons

RPC

Dating to the lates 60’s, RPC is one of the oldest programming client-server protocols for APIs. It is still used to this day. Although it has taken on many different forms.

RPC-based APIs are better for procedure or commands, while REST is more about modeling the data and state.

  • It is still popular in system programming, thus it have native support in Go-lang

And it is becoming popular in the crypto-currency space.

We’ll expand more in this area soon.

Legacy Tech

Here we’ll touch on some legacy tech for server client communication that are used less often. But for those we are history buffs, it might be helpful.

SOAP

SOAP was basically the precursor to REST.

Common Object Request Broker Architecture (COBRA)

COBRA was invented as Object Oriented Languages are becoming popular. It designed as the Objected Oriented technology compared to RPCs.

WebSockets

RESTful API is a design pattern, without constraint on the the communication protocol.

For most of the RESTful APIs, it is based on HTTP as the protocol. WebSockets have been another popular protocol for communication between client and server. It offers “real-time” and “two-way” communication.

Background on WebSockets

WebSockets vs HTTP

Even though WebSockets have some additional features such as two-way and real time communication, but it have its downsides also. Here are some articles that discussion pro and cons for WebSockets vs HTTP.

Resources for WebSockets by Languages

Binary Protocols

One common aspect of XML, JSON, REST and GraphQL is that the payload is usually human readable. Binary protocols is more intended to be read by a machine. It have the advance of concise, thus resulting in faster transmission. Here, we’ll discuss some common ones here.

Important: Binary Protocols is faster, but before you decide to use one, think about your application needs and where the bottle necks are.

Protocol Buffers (ProtoBuf)

Protocol Buffers are Google’s language-neutral, platform-neutral, extensible mechanism for serializing structured data – think XML, but smaller, faster, and simpler.

Language support:

Thrift

Thrift is created by Apache. They provide a code generation engine that create stubs for pretty much all languages.

MessagePack

The tagline for MessagePack is “It’s like JSON, but fast and small.” MessagePack is an efficient binary serialization format.

They also support almost every language:

Updated:

Leave a Comment