Comparisons of API Architectural Styles
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
- REST vs. GraphQL
- REST vs GraphQL APIs, the good, the bad, and the ugly
- HowToGraphQL of course says GraphQL is better
- Interesting debate on Quora with variety of views on if GraphQL is the REST killer.
- An Objective Comparison of GraphQL vs REST
- Just because Github have GraphQL doesn’t mean you should too
- Then again, there are article on how to make GraphQL and Restful API work well together: generate Restful API from GraphQL Schemas.
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.
- Java GraphQL Tutorials
- Javascript GraphQL Tutorials
- C Sharp GraphQL Tutorials
- Golang GraphQL Tutorials
- PHP GraphQL Tutorials
- Python GraphQL Tutorials
- Ruby GraphQL Tutorials
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
- XML vs JSON student paper
- This article urges people to stop comparing the two - although we can’t help it.
- XML vs JSON based web services: which is the best choice?
- An article from CEO of DigitalBazaar
- The author of this article urges you to choose wisely between the two
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.
- Introduction to RPC
- Lecture notes on RPC from a class at WPI
- More in-depth note also from a class at Cardiff University
- Understanding REST vs RPC
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.
- Ethereum uses a JSON RPC protocol.
- Monero also have a RPC protocol
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 basics
- Wiki on WebSockets
- Pusher, a company that depends on WebSockets, wrote an blog post on it
- WebSockets and Socket.IO
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.
- A discussion on StackOverflow on WebSockets vs HTTP
- A article comparing the performance of HTTP vs WebSockets
- HTTP and WebSockets: understanding capabilities of web communication technologies.
- REST over WebSockets instead of HTTP
- HTTP and WebSockets in the same application
Resources for WebSockets by Languages
- Javascript/NodeJS WebSockets Libraries
- Ruby WebSockets Libraries
- Python WebSockets Libraries
- Java WebSockets Libraries
- C Sharp WebSockets Libraries
- Golang WebSockets Libraries
- PHP WebSockets Libraries
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.
- Official home of Protocol Buffers
- Beating JSON’s performance with ProtoBuf
- 5 Reasons to use ProtoBuf instead of JSON
Language support:
- C++ ProtoBuf
- Java ProtoBuf
- Python ProtoBuf
- C Sharp ProtoBuf
- Javascript ProtoBuf
- Ruby ProtoBuf
- Go ProtoBuf
- PHP ProtoBuf
Thrift
Thrift is created by Apache. They provide a code generation engine that create stubs for pretty much all languages.
- Official Thrift homepage
- ProtoBuf vs Thrift vs Avro
- StackOverflow discussion
- Libraries for almost every language
MessagePack
The tagline for MessagePack is “It’s like JSON, but fast and small.” MessagePack is an efficient binary serialization format.
- Official homepage for MessagePack
- ProtoBuf vs Avro vs Thrift vs. MessagePack
- Comparing the performance of various serializers
They also support almost every language:
- MessagePack C Sharp
- MessagePack Java
- MessagePack Python
- MessagePack Ruby
- MessagePack Node
- MessagePack Scala
- MessagePack PHP
- MessagePack support in Go
