Programming, REST, Software engineering

SOAP, REST, gRPC and GraphQL – various ways of API design

API stands for Application Programming Interface which defines the way how it is possible to communicate with the system. In this article, I put focus on web technologies and their implementation in .NET.

Across many years, new design of APIs appeared in reply to new challenges, especially performance and implementation’s efficiency. Very first modern approach was RPC (Remote Procedure Call) proposed in 70s and implemented for the first time in 80s (source: Wikipedia). Inline with request-response concept, it was a milestone in distributed systems design and implementation.

In modern APIs, we may distinct 4 main technologies:

  • SOAP (Simple Object Access Protocol)
  • REST (REpresentational State Transfer)
  • gRPC (google Remote Procedure Call)
  • GraphQL (Graph Query Language)

Each of them have a bit different purpose and its support in .NET is various. SOAP, REST and gRPC are supported out-of-the-box, for GraphQL there is no default project template (by default). In case of GraphQL, 2 main options are available: HotChocolate and GraphQL.NET.

From historical perspective, SOAP is the oldest technology, rarely used for new projects, however it is worth to mention it as it is still available on the market, especially in legacy systems. GraphQL and gRPC are the latest “kids” of software development, however GraphQL has still poor support in .NET world. Also it is not well recognized by developers which does not make it real competitor to REST nowadays.

gRPC vs GraphQL

Therefore let’s dive into gRPC and GraphQL details. gRPC is designed for high performant, binary, bi-directional communication between microservices therefore is not good candidate for web clients. Web-gRPC ensures communication between web clients and backend services but it’s not the primary purpose of the technology, therefore before it will be used, all pros and cons have to be considered carefully. Considering GraphQL, it is human readable and easy to implement on client side. Also it gives a lot of features out-of-the-box (with many limitations).

gRPC

For .NET developers this is successor of SOAP (WCF) as .NET 5 removed its support. Communication is based on HTTP/2 protocol and it is using channels. The way how it is maintained, including closing, depends on language specific implementation. Also gRPC has embedded authentication and ensures encryption in transit (security by design).

gRPC is contract based (with .proto files). Protocol buffers is a language to describe data format. It is available in v2 and v3 however nowadays v3 is used the most often. Such descriptor is required as gRPC is binary protocol with full duplex stream support.

Communication in gRPC

GraphQL

GraphQL was designed to query data represented in graph form. It has schema first approach similar to SOAP or gRPC and there is a lot of client’s generators across the web.

By default, GraphQL supports:

  • queries – to retrieve the data
  • mutations – to modify the data
  • subscriptions – to ensure pub/sub via web sockets

Default communication method is POST (GET can be used alternatively) however the way how requests are send does not encourage GET. GraphQL has single endpoint with payload where query or mutation is specified with information to retrieve. Another aspect is sending information about the fields to return in a query and sending mutliple queries in single request (query batch).

The downside of multi-functionality embedded into GraphQL is limited number of supported technologies to resolve the problems (e.g. HotChocolate 10 in many features heavly depends on Redis and there is no alternatives).

Comparison

Besides gRPC, each solution is full cross platform (its limitation is HTTP/2 compatibility as prerequisite, older operating servers may not support it – e.g. IIS since version 10.0).

The table below is a comparison of selected features.

SOAPRESTGraphQLgRPC
CreatedMicrosoft, 1998 (publicly available since 1999)2000Facebook, 2012 (publicly available since 2015)Google, 2015
PurposeExtensible, neutral, verbose, with bi-directional communicationStateless, flexible, with no envelopeEfficient in frontend implementationHigh performant, microservices communication
Stateful/StatelessStateful or StatelessStatelessStatelessStateless
Communication
ProtocolAny HTTP version, TCP/IP, MQAny HTTP versionAny HTTP versionHTTP/2 only
Most often used formatXMLJSON, XMLJSONBinary
Request-response including streamRequest-response including streamRequest-response including streamRequest-response including stream
One-way/Two-waysTwo-waysOne-wayOne-wayTwo-ways
ContractRequired (XML)OptionalRequired (JSON)Required (proto defined)
Browser supportPartial (with additional libraries)YesYesPartial (through Web-gRPC library)
Library support (in .NET)WCF (till .NET 4.8)Yes (with MVC/WebAPI)External librarySince .NET 5
Additional features+ Caching out-of-the-box
+ Subscriptions (pub/sub) via web socket
Pros+ Well known by developers
+ A lot of tools
+ Well known by developers
+ A lot of tools
+ Flexible interface
+ Easy to use by frontend teams
+ Caching out-of-the-box
+ Allow to receive only selected fields
+ High performance
+ Well documented
Cons– Hard to maintain
– A lot of data send (envelops)
– Contract is optional– Not well documented
– Not wide propagated
– Not (yet) widely used therefore not well known by developers

Summary

Looking into the future, we may forget about SOAP and look forward on new solutions GraphQL and gRPC with all pros and cons of them. Also we need to remember that our solution is as good as libraries which we use. It is important factor in solution design. Altough we need to keep in mind that technologies evolves very fast and new solutions may appear very fast or current will be much improved.

Leave a Reply

Your email address will not be published.