Mastering RESTful Architecture: From Basics to Advanced HATEOAS

What?

Wikipedia: Representational State Transfer (REST) is a software architecture style proposed by Dr. Roy Fielding in his 2000 doctoral dissertation.

Roy Fielding was a principal designer of the HTTP protocol (versions 1.0 and 1.1); the HTTP/1.1 specification is based on REST principles. REST is a design style, not a standard, and an architecture that follows its principles is called RESTful.

Why?

In early web development the front‑end and back‑end were tightly coupled (e.g., PHP, JSP, ASP). With the rise of mobile and various client platforms, a unified interface is needed to serve Web, iOS, Android, and desktop applications, as well as platforms like Facebook, Weibo, and WeChat that expose services without an explicit front‑end, making RESTful APIs an ideal choice.

Understanding RESTful architecture starts with the term "Representational State Transfer"—"representation" refers to the resource's representation (e.g., JSON, XML), and "state transfer" refers to state changes performed via HTTP verbs.

Resource : the data, such as newsfeed, friends, orders.

Representational : the format used to present the resource, like JSON, XML, JPEG.

State Transfer : the change of state, realized through HTTP methods.

Resource‑Oriented Architecture (ROA) further defines RESTful design:

Resources are identified by URIs; interacting with a URI means accessing a resource.

Operations on resources include retrieval, creation, modification, and deletion, corresponding to HTTP GET, POST, PUT, and DELETE.

The representation of a resource is negotiated via the Accept and Content‑Type headers.

Representations can be XML, HTML, or any other suitable format, depending on whether the consumer is a machine or a human.

How?

A Web API that follows REST design is called a RESTful API. It defines resources from three perspectives:

Intuitive, short resource URIs, e.g., http://example.com/resources/ , where each URI represents a distinct resource.

Media types exchanged for the resource, such as JSON, XML, YAML.

Supported request methods on the resource, e.g., POST, GET, PUT, DELETE.

Example diagram:

Typical use of HTTP methods in a RESTful API:

For a collection URI ( http://example.com/resources/) GET lists resources, PUT replaces the entire collection, POST creates a new resource, and DELETE removes the collection. For an individual resource URI ( http://example.com/resources/142) the methods operate on that single resource accordingly.

Common Misunderstandings about REST

When REST was introduced in 2000 it was ahead of its time. Many developers misunderstood HTTP's design intent, leading to inefficient usage until the Web 2.0 era. Early service technologies like DCOM, EJB, SOAP/WSDL conflicted with REST's web‑centric style.

Ruby on Rails popularized REST, but its implementation limited REST to CRUD operations mapped to GET/POST/PUT/DELETE, narrowing the perceived scope. Other frameworks (e.g., Struts, Spring MVC) copied this pattern, causing developers to equate REST solely with CRUD‑based APIs, even when they merely used HTTP without adhering to REST principles.

Fielding later emphasized that true REST APIs must be hypertext‑driven (HATEOAS), meaning the API should provide hypermedia links that guide client state transitions.

Advanced REST Design

When discussing REST maturity, many refer to Richardson's REST Maturity Model.

Most WS‑* services and POX use a single URI with a single HTTP method, treating HTTP as a transport protocol rather than an application protocol. A common mistake is embedding verbs in URIs, e.g., http://example.com/getOrder?orderId=1234, whereas resources should be nouns and actions should be expressed via HTTP methods. Additionally, using GET for state‑changing operations (e.g., http://example.com/updateOrder?id=1234&coffee=latte) violates HTTP semantics.

Level 2: Each URI Represents a Resource, Supporting HTTP Verbs

Multiple URIs should each denote a distinct resource, and each resource can be manipulated with appropriate HTTP verbs (POST, GET, PUT, DELETE). The request headers and payload carry business logic, and the response status codes reflect operation outcomes. This is the typical level most RESTful APIs achieve.

Level 3: HATEOAS – Using Hypermedia as the Engine of Application State

According to Roy Fielding, hypermedia is a prerequisite for true REST. Hypermedia combines hyperlinks with multimedia, allowing clients to discover available actions through links embedded in responses.

Example response illustrating hypermedia links:

GET https://api.example.com/profile {
  "name": "Steve",
  "picture": {
    "large": "https://somecdn.com/pictures/1200x1200.png",
    "medium": "https://somecdn.com/pictures/100x100.png",
    "small": "https://somecdn.com/pictures/10x10.png"
  }
}

The response includes URLs for different image sizes, enabling the client to choose the appropriate representation without downloading unnecessary data, reducing bandwidth and improving flexibility.

Hypermedia fundamentally relies on the <link> element, where linked resources describe a protocol of steps (e.g., ordering a coffee) that drive the application state.

Source: http://blog.csdn.net/lz0426001/article/details/52370193