REST API Design Rulebook

Chapter 1. Introduction

Hello World Wide Web

The Web started in the “data acquisition and control” group at the European Organization for Nuclear Research (CERN), in Geneva, Switzerland. It began with a computer programmer who had a clever idea for a new software project.

In December of 1990, to facilitate the sharing of knowledge, Tim Berners-Lee started a non-profit software project that he called “WorldWideWeb.”^[6] After working diligently on his project for about a year, Berners-Lee had invented and implemented:

• The Uniform Resource Identifier (URI), a syntax that assigns each web document a unique address

• The HyperText Transfer Protocol^[7] (HTTP), a message-based language that computers could use to communicate over the Internet.

• The HyperText Mark-up Language (HTML), to represent informative documents that contain links to related documents.

• The first web server.^[8]

• The first web browser, which Berners-Lee also named “WorldWideWeb” and later renamed “Nexus” to avoid confusion with the Web itself.

• The first WYSIWYG^[9] HTML editor, which was built right into the browser.

On August 6, 1991, on the Web’s first page, Berners-Lee wrote,

The WorldWideWeb (W3) is a wide-area hypermedia information retrieval initiative aiming to give universal access to a large universe of documents.^[10]

From that moment, the Web began to grow, at times exponentially. Within five years, the number of web users skyrocketed to 40 million. At one point, the number was doubling every two months. The “universe of documents” that Berners-Lee had described was indeed expanding.

In fact, the Web was growing too large, too fast, and it was heading toward collapse.

The Web’s traffic was outgrowing the capacity of the Internet infrastructure. Additionally, the Web’s core protocols were not uniformly implemented and they lacked support for caches and other stabilizing intermediaries. With such rapid expansion, it was unclear if the Web would scale to meet the increasing demand.

Web Architecture

In late 1993, Roy Fielding, co-founder of the Apache HTTP Server Project,^[11] became concerned by the Web’s scalability problem.

Upon analysis, Fielding recognized that the Web’s scalability was governed by a set of key constraints. He and others set out to improve the Web’s implementation with a pragmatic approach: uniformly satisfy all of the constraints so that the Web could continue to expand.

The constraints, which Fielding grouped into six categories and collectively referred to as the Web’s architectural style, are:

1. Client-server

2. Uniform interface

3. Layered system

4. Cache

5. Stateless

6. Code-on-demand

Each constraint category is summarized in the following subsections.

Client–Server

The separation of concerns is the core theme of the Web’s client-server constraints. The Web is a client-server based system, in which clients and servers have distinct parts to play. They may be implemented and deployed independently, using any language or technology, so long as they conform to the Web’s uniform interface.

Uniform Interface

The interactions between the Web’s components—meaning its clients, servers, and network-based intermediaries—depend on the uniformity of their interfaces. If any of the components stray from the established standards, then the Web’s communication system breaks down.

Web components interoperate consistently within the uniform interface’s four constraints, which Fielding identified as:

1. Identification of resources

2. Manipulation of resources through representations

3. Self-descriptive messages

4. Hypermedia as the engine of application state (HATEOAS)

The four interface constraints are summarized in the following subsections.

Identification of resources

Each distinct Web-based concept is known as a resource and may be addressed by a unique identifier, such as a URI. For example, a particular home page URI, like http://www.oreilly.com, uniquely identifies the concept of a specific website’s root resource.

Manipulation of resources through representations

Clients manipulate representations of resources. The same exact resource can be represented to different clients in different ways. For example, a document might be represented as HTML to a web browser, and as JSON to an automated program. The key idea here is that the representation is a way to interact with the resource but it is not the resource itself. This conceptual distinction allows the resource to be represented in different ways and formats without ever changing its identifier.

Self-descriptive messages

A resource’s desired state can be represented within a client’s request message. A resource’s current state may be represented within the response message that comes back from a server. As an example, a wiki page editor client may use a request message to transfer a representation that suggests a page update (new state) for a server-managed web page (resource). It is up to the server to accept or deny the client’s request.

The self-descriptive messages may include metadata to convey additional details regarding the resource state, the representation format and size, and the message itself. An HTTP message provides headers to organize the various types of metadata into uniform fields.

Hypermedia as the engine of application state (HATEOAS)

A resource’s state representation includes links to related resources. Links are the threads that weave the Web together by allowing users to traverse information and applications in a meaningful and directed manner. The presence, or absence, of a link on a page is an important part of the resource’s current state.

Layered System

The layered system constraints enable network-based intermediaries such as proxies and gateways to be transparently deployed between a client and server using the Web’s uniform interface. Generally speaking, a network-based intermediary will intercept client-server communication for a specific purpose. Network-based intermediaries are commonly used for enforcement of security, response caching, and load balancing.

Cache

Caching is one of web architecture’s most important constraints. The cache constraints instruct a web server to declare the cacheability of each response’s data. Caching response data can help to reduce client-perceived latency, increase the overall availability and reliability of an application, and control a web server’s load. In a word, caching reduces the overall cost of the Web.

A cache may exist anywhere along the network path between the client and server. They can be in an organization’s web server network, within specialized content delivery networks (CDNs), or inside a client itself.

Stateless

The stateless constraint dictates that a web server is not required to memorize the state of its client applications. As a result, each client must include all of the contextual information that it considers relevant in each interaction with the web server. Web servers ask clients to manage the complexity of communicating their application state so that the web server can service a much larger number of clients. This trade-off is a key contributor to the scalability of the Web’s architectural style.

Code-On-Demand

The Web makes heavy use of code-on-demand, a constraint which enables web servers to temporarily transfer executable programs, such as scripts or plug-ins, to clients. Code-on-demand tends to establish a technology coupling between web servers and their clients, since the client must be able to understand and execute the code that it downloads on-demand from the server. For this reason, code-on-demand is the only constraint of the Web’s architectural style that is considered optional. Web browser-hosted technologies like Java applets, JavaScript, and Flash exemplify the code-on-demand constraint.

Web Standards

Fielding worked alongside Tim Berners-Lee and others to increase the Web’s scalability. To standardize their designs, they wrote a specification for the new version of the Hypertext Transfer Protocol, HTTP/1.1.^[12] They also formalized the syntax of Uniform Resource Identifiers (URI) in RFC 3986.^[13]

Adoption of these standards quickly spread across the Web and paved the way for its continued growth.

REST

In the year 2000, after the Web’s scalability crisis was averted, Fielding named and described the Web’s architectural style in his Ph.D. dissertation.^[14] “Representational State Transfer” (REST) is the name that Fielding gave to his description^[15] of the Web’s architectural style, which is composed of the constraints outlined above.

REST APIs

Web services are purpose-built web servers that support the needs of a site or any other application. Client programs use application programming interfaces (APIs) to communicate with web services. Generally speaking, an API exposes a set of data and functions to facilitate interactions between computer programs and allow them to exchange information. As depicted in Figure 1-1, a Web API is the face of a web service, directly listening and responding to client requests.

Figure 1-1. Web API

The REST architectural style is commonly applied to the design of APIs for modern web services. A Web API conforming to the REST architectural style is a REST API. Having a REST API makes a web service “RESTful.” A REST API consists of an assembly of interlinked resources. This set of resources is known as the REST API’s resource model.

Well-designed REST APIs can attract client developers to use web services. In today’s open market where rival web services are competing for attention, an aesthetically pleasing REST API design is a must-have feature.

REST API Design

For many of us, designing a REST API can sometimes feel more like an art than a science. Some best practices for REST API design are implicit in the HTTP standard, while other pseudo-standard approaches have emerged over the past few years. Yet today, we must continue to seek out answers to a slew of questions, such as:

• When should URI path segments be named with plural nouns?

• Which request method should be used to update resource state?

• How do I map non-CRUD operations to my URIs?

• What is the appropriate HTTP response status code for a given scenario?

• How can I manage the versions of a resource’s state representations?

• How should I structure a hyperlink in JSON?

Rules

This book presents a set of REST API design rules that aim to provide clear and concise answers to the nagging questions listed above. The rules are here to help you design REST APIs with consistency that can be leveraged by the clients that use them. These rules can be followed as a complete set or a la carte. You may contest the rules, but I believe that each one warrants careful consideration.

Many of this book’s design rules are drawn from the best practices that have become de facto standards. If you have some experience with the design of REST APIs, then you are likely to be familiar with the rules related to URI design in Chapter 2 and the use of HTTP in Chapter 3. In contrast, most of the rules presented in Chapter 4 and Chapter 5 (particularly those that deal with media types and representational forms) are my solutions in the absence of consensus.

Note

When used in the context of rules, the key words: “must,” “must not,” “required,” “shall,” “shall not,” “should,” “should not,” “recommended,” “may,” and “optional” are to be interpreted as described in RFC 2119.^[16]

WRML

I’ve invented a conceptual framework called the Web Resource Modeling Language (WRML) to assist with the design and implementation of REST APIs. WRML, pronounced like “wormle,” originated as a resource model diagramming technique that uses a set of basic shapes to represent each of the resource archetypes discussed in Resource Archetypes. The scope of WRML increased with the creation of the application/wrml media type,^[17] which has pluggable format and schema components, as described in Media Type Design. In many of the book’s later rules, I’ll use ideas from WRML to fill in the gaps in current best practices with rational advice for common situations.

In Chapters 5 and 6 you’ll notice that many of the rules include examples that use the JavaScript Object Notation (JSON) to format representations.^[18] JSON is an important format that has many advantages, such as native JavaScript support, near-ubiquitous adoption, and familiar syntax. However, by itself the JSON format does not provide uniform structures for some of the most important REST API concepts, specifically links, link relations, and schemas. The rules in Hypermedia Representation and Schema Representation, use WRML to demonstrate JSON-formatted representational forms for each of these core constructs.

Finally, Chapter 7 asserts that uniformity of API design is not merely an academic pursuit. On the contrary it holds the promise of improving the lives of programmers by empowering us with a rich set of development tools and frameworks that we can leverage to design and develop REST APIs.

Recap

This chapter presented a synopsis of the Web’s invention and stabilization. It motivated the book’s rule-oriented presentation and introduced WRML, a conceptual framework whose ideas promote a uniform REST API design methodology. Subsequent chapters will build on this foundation to help us leverage REST in API designs. Table 1-1 summarizes the vocabulary terms that were introduced in this chapter.

Table 1-1. Vocabulary review

Term	Description
Application Programming Interface (API)	Exposes a set of data and functions to facilitate interactions between computer programs.
Architectural constraint	Limits the behavior of a system’s components to enforce uniformity and achieve some desired property.
Architectural style	In his Ph.D. dissertation, Roy Fielding used this term to describe a set of constraints that restrict the behavior of a system’s interconnected components.
Cache	REST constraints that enable network-based intermediaries to hold on to resource state representations, which helps web servers meet the demands of their clients.
Client–server	REST constraints that separate the concerns of its two primary components, which allows their implementations to evolve independently.
Code-on-demand	A REST constraint that optionally allows a web server to transfer executable programs to its clients on an as-needed basis.
Entity body	Section of an HTTP message that is designated to hold the (optional) content, which may be a resource representation.
Entity headers	Section of an HTTP message that can communicate meta information regarding a resource and its representation.
HATEOAS	Acronym that stands for REST’s “Hypermedia as the Engine of Application State” uniform interface constraint, which refers to the practice of providing a state-aware list of links to convey a resource’s available “actions.”
Hypermedia	An extension of hypertext that enables multiple formats to be combined and tethered together with links to design a multi-media information network.
Hypertext	Text-based documents containing embedded links to related documents, which creates a navigable mesh of information.
HyperText Mark-up Language (HTML)	Created by Tim Berners-Lee to represent the state of a web resource’s information and relationships.
HyperText Transfer Protocol (HTTP)	Originally developed by Tim Berners-Lee, this is a message-based language that computers could use to communicate over the Internet.
Hypertext Transfer Protocol version 1.1 (HTTP/1.1)	Roy Fielding, Tim Berners-Lee, and others contributed to the standardization of this most recent version of the communication protocol.
JavaScript	A powerful scripting language that is commonly used by web developers.
JavaScript Object Notation (JSON)	A standardized text format that was derived from JavaScript and is used for structured data exchange.
Layered system	REST constraints that enable network-based intermediaries to sit between a client and server without compromising the uniform interface constraints.
Media type	A syntax that describes the form of content.
Message	Self-descriptive envelope that is often used to carry a representation of a resource’s state.
Representation	The formatted state of a resource, which may be transferred via messages that are passed between components.
Representational State Transfer (REST)	Roy Fielding’s derivation of the Web’s architectural style.
Request message	Sent from clients to interact with a URI-indicated web resource. May contain a representation that suggests a resource state.
Resource	Any Web-based concept that can be referenced by a unique identifier and manipulated via the uniform interface.
Resource identifier	A universally unique ID of a specific Web-based concept.
Resource model	An assembly of interlinked Web-based concepts.
Resource state representation	The rendered state of a web server-owned resource; transferred between an application’s client and server.
Response message	Returned from servers to indicate the results of a client’s request. May contain a representation to convey a resource state.
REST API	A web service interface that conforms to the Web’s architectural style.
Scalability	The ability to gracefully handle an increasing workload.
Stateless	A REST constraint that restricts a web server from holding on to any client-specific state information, which helps it support more clients.
Uniform interface	A set of four REST constraints that standardize the communication between Web-based components.
Uniform Resource Identifier (URI)	A syntax invented by Tim Berners-Lee to assign each web resource a unique ID.
Web API	Used by clients to interact with a web service.
Web browser (browser)	Common type of web client. Tim Berners-Lee developed the first one, which was able to view and edit HTML documents.
Web client (client)	A computer program that follows REST’s uniform interface in order to accept and transfer resource state representations to servers.
Web component (component)	A client, network-based intermediary, or server that complies with REST’s uniform interface.
Web Resource Modeling Language (WRML)	A conceptual framework whose ideas can be leveraged to design and implement uniform REST APIs.
Web server (server)	A computer program that follows REST’s uniform interface constraints in order to accept and transfer resource state representations to clients.
Web service	A web server programmed with specific, often reusable, logic.

---

^[6] The WorldWideWeb project was later renamed the “World Wide Web,” with added spaces.

^[7] Berners-Lee, Tim. The Original HTTP as defined in 1991, W3C, 1991 (http://www.w3.org/Protocols/HTTP/AsImplemented.html).

^[8] The first web server is still up and running at http://info.cern.ch.

^[9] WYSIWYG is an acronym for What You See Is What You Get.

^[10] Berners-Lee, Tim. World Wide Web, W3C, 1991 (http://www.w3.org/History/19921103-hypertext/hypertext/WWW/TheProject.html).

^[11] http://httpd.apache.org.

^[12] Fielding, Roy T., Tim Berners-Lee, et al. HTTP/1.1, RFC 2616, RFC Editor, 1999 (http://www.rfc-editor.org/rfc/rfc2616.txt).

^[13] Berners-Lee, Tim, Roy T. Fielding, et al. Uniform Resource Identifier (URI): Generic Syntax, RFC 3986, RFC Editor, 2005 (http://www.rfc-editor.org/rfc/rfc3986.txt).

^[14] Fielding, Roy Thomas. Architectural Styles and the Design of Network-based Software Architectures, Doctoral dissertation, University of California, Irvine, 2000 (http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm).

^[15] “REST” is the name of the description, or derivation, of the Web’s architectural style.

^[16] Bradner, Scott. Key words for use in RFCs to Indicate Requirement Levels, RFC 2119, RFC Editor, 1997 (http://www.rfc-editor.org/rfc/rfc2119.txt).

^[17] The application/wrml media type’s IANA registration is pending—see http://www.wrml.org for the most up-to-date information.

^[18] http://www.json.org