[The API Book] Digest 2023–06–16

The new Section “HTTP APIs & Rest Architecture Principles” started! Five chapters are already published:

Chapter 33. On the HTTP API Concept and Terminology

The domain name system, which allows for assigning human-readable aliases to IP addresses, has proved to be a convenient abstraction with almost universal adoption. Introducing domain names necessitated the development of new protocols at a higher level than TCP/IP. For text (hypertext) data this protocol happened to be HTTP 0.9 developed by Tim Berners-Lee and published in 1991. Besides enabling the use of network node names, HTTP also provided another useful abstraction: assigning separate addresses to endpoints working on the same network node.

Chapter 34. The REST Myth

In 2000, Roy Fielding, one of the authors of the HTTP and URI specifications, published his doctoral dissertation titled “Architectural Styles and the Design of Network-based Software Architectures,” the fifth chapter of which was named “Representational State Transfer (REST).”

As anyone can attest by reading this chapter, it features a very much abstract overview of a distributed client-server architecture that is not bound to either HTTP or URL. Furthermore, it does not discuss any API design recommendations. In this chapter, Fielding methodically enumerates restrictions that any software engineer encounters when developing distributed client-server software.

Chapter 35. Components of an HTTP Request and Their Semantics

An HTTP request consists of (1) applying a specific verb to a URL, stating (2) the protocol version, (3) additional meta-information in headers, and (4) optionally, some content (request body)…

Chapter 36. Advantages and Disadvantages of HTTP APIs

The reader might wonder why this dichotomy exists in the first place, i.e., why do some HTTP APIs rely on HTTP semantics while others reject it in favor of custom arrangements? For example, if we consider the JSON-RPC response format, we will quickly notice that it might be replaced with standard HTTP protocol functionality.

Chapter 37. Organizing an HTTP API Based on the REST Principles

What does it mean exactly to “follow the protocol’s semantics” and “develop applications in accordance with the REST architectural style”? Remember, we are talking about the following principles:

• Operations must be stateless
• Data must be marked as cacheable or non-cacheable
• There must be a uniform interface of communication between components
• Network systems are layered.

We need to apply these principles to an HTTP-based interface, adhering to the letter and spirit of the standard:

• The URL of an operation must point to the resource the operation is applied to, serving as a cache key for GET operations and an idempotency key for PUT and DELETE operations.
• HTTP verbs must be used according to their semantics.
• Properties of the operation, such as safety, cacheability, idempotency, as well as the symmetry of GET / PUT / DELETE methods, request and response headers, response status codes, etc., must align with the specification.