Absract Programming Interfaces (APIs)

Created: January 05, 2025

RESTful APIs

REST (Representational State Transfer) is a software architectural style that was created to guide the design and development of the architecture for the World Wide Web. REST defines a set of constraints for how the architecture of a distributed, Internet-scale hypermedia system, such as the Web, should behave.

When an API conforms to REST, it is called a RESTful API.

In order for an API to be considered RESTful, it has to conform to these criteria:

A client-server architecture made up of clients, servers, and resources, with requests managed through HTTP.
Stateless client-server communication, meaning no client information is stored between get requests and each request is separate and unconnected.
Cacheable data that streamlines client-server interactions.
A uniform interface between components so that information is transferred in a standard form. This requires that:
- resources requested are identifiable and separate from the representations sent to the client (i.e. URIs are used to identify resources).
- resources can be manipulated by the client via the representation they receive because the representation contains enough information to do so.
- self-descriptive messages returned to the client have enough information to describe how the client should process it.
- hypertext/hypermedia is available, meaning that after accessing a resource the client should be able to use hyperlinks to find all other currently available actions they can take.
A layered system that organizes each type of server (those responsible for security, load-balancing, etc.) involved the retrieval of requested information into hierarchies, invisible to the client.
Code-on-demand (optional): the ability to send executable code from the server to the client when requested, extending client functionality.

REST was created by Roy Fielding in his 2000 doctoral dissertation at UC Irvine, “Architectural Styles and the Design of Network-based Software Architectures.”

SOAP APIs

Remote Procedure Calls (RPCs)

RPC APIs allow developers to call remote functions in external servers as if they were local to their software. For example, to call a remote function add that takes two arguments a and b and returns their sum, the developer would write:

result = add(1, 2)

Many implementations of RPC APIs exist, including:

Remote Method Invocation (RMI/Java)
Distributed Component Object Model (DCOM/Microsoft)
Common Object Request Broker Architecture (CORBA)
gRPC

RPC could be implemented using HTTP, using the usual HTTP methods, but it is not RESTful.

Flaws with RPC APIs

Networks are unreliable, so RPCs can fail.
A request can timeout.
If a previous request is deemed lost (but is just delayed), the server may execute the request twice.
Latency can make the client wait for a long time.
Encoding (serialisation) and decoding can be complicated for complex data types.
Data type tranlation may not be perfect if the client and server are written in different languages.

gRPC (Google Remote Procedure Call)

gRPC is the latest RPC framework to gain popularity. It is based on Protocol Buffers, a binary serialisation format. gRPC is language-agnostic and can be used with any programming language.

To implement gRPC APIs, you create gRPC services with methods that clients can call. You then define a contract between a client and a server. This contract stipulates the procedures the clients can call from the service, the parameters that can be passed to those procedures, and the types of data that will be returned. The client and the server then use this contract to generate code in their respective languages for calling the procedures and exchanging data. This generated code covers all communication details like message serialization, network calls, and error handling.

gRPC supports four types of service methods:

Unary RPC: A unary service method takes one input and returns one output.
Server Streaming RPC: A server streaming service method receives one input from the client and sends a stream of outputs. It can also send back multiple outputs as data becomes available.
Client Streaming RPC: Client streaming service methods open a connection to a server, and then when the server acknowledges the stream can begin, the client side can begin sending data until it terminates the stream.
Bidirectional Streaming RPC: Bidirectional streaming service methods simultaneously send and receive data streams in both directions.

Advantages of gRPC

gRPC supports streaming connection mode. Streaming mode sends or receives data in chunks, which can improve performance when the data is too large to send or receive at once. This allows clients to continuously receive data from the server without waiting for the entire response to arrive. As a result, users don’t have to wait until all the data transfer is complete.
- During streaming, the connection between the client and the server is maintained, meaning no data is lost or corrupted while transmitted. gRPC streaming is ideal for real-time applications like chat or gaming.
gRPC supports plugging in load balancing, tracing, health checking, and authentication. This makes it easy to set up and manage high-performance systems. gRPC is modular, so it’s simple to set up and configure its different feature sets.

Disadvantages of gRPC

All libraries are maintained by Google to serve their own needs.
Steep learning curve.
Incompatible with some browsers.
Most Protobuf encoders/decoders expect to fully parse an entire message and give the full response to the consumer but memory is finite and sometimes you might want larger messages. Sometimes you want to stream parts of these larger messages somewhere else and not keep the entire message in memory. Therefore, if you want to, for example, upload large files you’re going to need to implement some kind of chunking. While chunking is a reasonable solution for handling large files, the absence of a standardized approach within gRPC might lead to inconsistent implementations and increased development effort.