To understand why REST is the dominating architectural style for most web services, we will need to understand what was available before the rise of REST and the challenges that made this change so important in the way that distributed services are built.

The pre-REST era

Before REST, the web services landscape was dominated by protocols such as Simple Object Access Protocol (SOAP) and Extensible Markup Language–Remote Procedure Call (XML-RPC). These were powerful but complex standards that allowed for detailed communication between clients and servers. However, they were often seen as cumbersome due to their verbose nature and the strict requirements they imposed on developers.

SOAP, for instance, required developers to write extensive XML documents with specific calls and responses. It was notorious for its complexity and difficulty in debugging. Similarly, XML-RPC, while simpler than SOAP, still involved significant overhead for simple requests and...

Up to this point, we have only mentioned the key principles of REST. Let us dive deeper to understand these principles in more detail.

Uniform interface

The uniform interface is the cornerstone of any REST design, promoting a standardized way of interacting with a given set of resources. This principle encompasses four key constraints:

• Identification of resources: Each resource, whether it is a document, image, or service, is identified using a unique uniform resource identifier (URI)
• Manipulation of resources via representations: When a client possesses a representation of a resource, along with any attached metadata, it can modify or delete the resource on the server if it has the necessary permissions
• Self-descriptive messages: Each message contains enough information to describe how to process it, which may include the representation format and the desired state transitions
• Hypermedia as the engine of application...

One way to understand the concept of RESTfulness is through the Richardson Maturity Model, which outlines various levels of adherence to REST principles in API design.

Named after Leonard Richardson, who introduced it in 2008, the model consists of four levels, each representing progression toward more RESTful design:

Figure 1.2 – Richardson Maturity Model diagram

Level 0 – the swamp of Plain Old XML (POX)

At this level, APIs are characterized by a single URI for all operations, typically using HTTP POST requests. The payloads are often XML-based, and there is no distinction between different resource types or HTTP methods. This level lacks the fundamental principles of REST, such as resource identification and separation of concerns.

Level 1 – resources

This level introduces the concept of resources, where each entity in the system is represented as a unique URI. However, HTTP methods are not fully utilized...

JSON is a simple data format which is designed for easy reading and writing for humans, while also being straightforward for machines to process and create. One small feature that a human user may miss is that JSON does not support comments.

It is based on a subset of the JavaScript programming language and is completely language-independent, with parsers available for every programming language.

A JSON document is built from two structures:

• A collection of name/value pairs: In various languages, this is implemented as an object, record, struct, dictionary, hash table, keyed list, or associative array
• An ordered list of values: In most languages, this is implemented as an array, vector, list, or sequence

Here is a simple example of a JSON document for a book object:

{
  "book": {
    "title": "Mastering RESTful JSON Essentials",
    "author": "Multiple Authors",
   ...

Guidelines serve as a roadmap for developers, outlining best practices and standards that should be followed during the API development process. They are a set of rules that aim to prevent common pitfalls and promote excellence in API design. Here are some of the most important aspects of following well-established guidelines:

• Consistency and predictability: Developers ensure a level of consistency that makes APIs predictable and easier to understand. This uniformity is essential for both the developers who create APIs and the users who consume them.
• Interoperability: Guidelines often emphasize the use of standard protocols and data formats, which fosters interoperability across different platforms and technologies. This is particularly important in a diverse ecosystem where APIs serve as the bridge between various software components.
• Scalability: Well-designed APIs that adhere to guidelines are more likely to be scalable...

Here, we will explore some common use cases for REST APIs with examples that illustrate their practical applications:

• Integration with third-party services: Syncing data between different platforms, such as Customer Relationship Management (CRM) and Enterprise Resource Planning (ERP) systems
• Social media services: Enabling social interactions and content sharing on various platforms
• E-commerce transactions: Managing product listings, orders, and payments
• Internet of Things (IoT): Connecting and controlling smart devices remotely
• Health and fitness tracking: Aggregating data from various health and fitness devices

In the next section, we will discuss the impact of the architectural design of REST APIs in a complete system and its clients.

The need to design and implement APIs can occur in many different contexts. The goal we want to achieve with an API and the role it plays within the architecture of the application or system being developed influences the relative importance of the various API aspects described in the respective chapters of this book. The unique mix of architectural aspects also impacts the choice of approaches and techniques to implement APIs.

The following sections present the most common patterns.

Cross-organizational public APIs

APIs consumed beyond organizational boundaries are the closest to the original application of web technologies.

Controlling all API clients is unfeasible. Public APIs with numerous independent consumers frequently prioritize backward compatibility over other design goals. The introduction of incompatible changes incurs a substantial cost associated with supporting multiple API versions at the same time.

Lastly...

This section presents some of the existing alternatives in the market to REST APIs and their comparison. It is good to know that REST is not always the best option for every case, and it is wise to be able to differentiate between the existing options available. Let us mention some examples here:

Remote Procedure Call (RPC)

RPC is an API style that obfuscates the existence of an API, rendering it akin to a standard procedure invocation (or a method in object-oriented languages) in a specific programming language. This style encompasses SOAP web services and XML-RPC.

Other notable representatives include CORBA (utilized by Enterprise Java Beans) and gRPC (a new one with support for numerous programming languages). gRPC delivers performance benefits due to its use of efficient binary message encoding.

RPC APIs are optimally suited for integrations where the number of clients is limited, and the API provider can exert control over them.

Their...

In this book, we will develop a project to apply the concepts mentioned in this chapter, having hands-on practice and experience. We will build two APIs that will communicate with each other.

The first API will be a Product API, which will be introduced in Chapter 2. This API, as its name suggests, is focused on product operations, such as reading product data and adding new products.

The second API will be the Order Management API. It will be introduced in Chapter 4 and will hold the orders containing the products stored in the first API, so they will communicate with each other.

Throughout the chapters, you will be able to implement these APIs, apply most of the best practices mentioned in this chapter, evolve these, document, test, and version to guarantee backward compatibility, implement tracing tools, and deploy to the cloud.

In this chapter, you learned the difference between REST and RESTful, and why the REST approach is the preferred method for building API web services compared to previous methods used before.

We have investigated the principles of REST architecture, the levels of using the Richardson Maturity Model, and the existing alternatives to REST.

Then, we looked at the role of JSON in REST services and the importance of following well-defined guidelines proven by numerous projects while developing REST web services.

Lastly, we investigated the architectural impact of REST API design and the project that will be built throughout this book in the following chapters.

This chapter presents the basics for you to get started with the upcoming content that will be presented and built throughout this book.

In the next chapter, we will explore the design and practical implementation of RESTful APIs using Spring Boot.