What's the difference between REST & RESTful

REST vs. RESTful: Understanding the Nuances of Web Service Design

Explore the fundamental differences between REST as an architectural style and RESTful as an implementation, and learn how to design truly RESTful APIs.

In the world of web services, the terms REST and RESTful are often used interchangeably, leading to confusion. While closely related, they represent distinct concepts. REST (Representational State Transfer) is an architectural style, a set of constraints and principles for designing networked applications. RESTful, on the other hand, describes a web service that adheres to these REST principles. This article will demystify these terms, clarify their differences, and guide you through the core tenets of building truly RESTful APIs.

What is REST? The Architectural Style

REST is not a protocol or a standard, but rather a set of architectural constraints that, when applied, promote scalability, simplicity, and reliability in distributed systems. Coined by Roy Fielding in his 2000 doctoral dissertation, REST defines how clients and servers should interact. The core principles of REST are:

1. Client-Server Architecture: Separation of concerns between the client and the server, allowing independent evolution.
2. Statelessness: Each request from client to server must contain all the information needed to understand the request. The server should not store any client context between requests.
3. Cacheability: Clients and intermediaries can cache responses, improving performance and scalability.
4. Uniform Interface: A fundamental constraint that simplifies the overall system architecture. It includes:
   • Resource Identification: Resources are identified by URIs.
   • Resource Manipulation through Representations: Clients interact with resources by exchanging representations (e.g., JSON, XML).
   • Self-Descriptive Messages: Each message includes enough information to describe how to process the message.
   • Hypermedia as the Engine of Application State (HATEOAS): Clients navigate the application state by following links provided in resource representations.
5. Layered System: A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way.
6. Code-On-Demand (Optional): Servers can temporarily extend or customize client functionality by transferring executable code (e.g., JavaScript).

flowchart TD
    A[Client] --> B{Request Resource (URI)};
    B --> C[Server];
    C --> D{Process Request (Stateless)};
    D --> E[Retrieve Resource Data];
    E --> F[Create Representation (e.g., JSON)];
    F --> G{Add Hypermedia Links (HATEOAS)};
    G --> H[Send Response];
    H --> I[Client (Cacheable)];
    I --> J{Manipulate State via Links};
    J --> B;

    subgraph REST Constraints
        C-S[Client-Server]
        SL[Stateless]
        CA[Cacheable]
        UI[Uniform Interface]
        LS[Layered System]
    end

    UI --> R[Resource Identification]
    UI --> RM[Resource Manipulation]
    UI --> SDM[Self-Descriptive Messages]
    UI --> HATEOAS[HATEOAS]

    style C-S fill:#f9f,stroke:#333,stroke-width:2px
    style SL fill:#f9f,stroke:#333,stroke-width:2px
    style CA fill:#f9f,stroke:#333,stroke-width:2px
    style UI fill:#f9f,stroke:#333,stroke-width:2px
    style LS fill:#f9f,stroke:#333,stroke-width:2px

Core Principles of the REST Architectural Style

What Does 'RESTful' Mean? Adhering to REST Principles

A web service is considered 'RESTful' if it adheres to the architectural constraints defined by REST. This means it leverages standard HTTP methods (GET, POST, PUT, DELETE, PATCH) to perform operations on resources, identifies resources using URIs, and communicates state through representations. The degree to which a service is RESTful can be measured using the Richardson Maturity Model, which outlines four levels of REST maturity:

• Level 0: The Swamp of POX (Plain Old XML): A single URI, using POST for all operations, often with custom XML payloads. Not RESTful.
• Level 1: Resources: Introduces the concept of resources, each with its own URI. Still uses POST for all operations on those resources.
• Level 2: HTTP Verbs: Utilizes HTTP methods (GET, POST, PUT, DELETE) correctly for different operations on resources. This is where most 'RESTful' APIs operate.
• Level 3: Hypermedia Controls (HATEOAS): The highest level of maturity, where the API guides the client through the application state by providing hypermedia links within resource representations. This is the true essence of RESTfulness, enabling clients to discover available actions dynamically without prior knowledge of the API's structure.

Key Differences and Practical Implications

The primary difference is that REST is the theoretical blueprint, while RESTful is the practical implementation that follows that blueprint. Think of it this way:

• REST: The idea, the philosophy, the set of rules.
• RESTful: An API that is built according to those rules.

Building a truly RESTful API, especially one that reaches Level 3 of the Richardson Maturity Model, offers significant benefits:

• Decoupling: Client and server are highly decoupled, allowing independent evolution.
• Discoverability: Clients can discover available actions and navigate the API dynamically.
• Scalability: Statelessness and cacheability contribute to better scalability.
• Maintainability: A uniform interface simplifies understanding and interaction.

However, implementing HATEOAS can add complexity to both the server-side API design and the client-side consumption logic. Many developers opt for Level 2 RESTful APIs for simplicity, sacrificing some of the dynamic discoverability for ease of development.

GET /orders/123 HTTP/1.1
Host: api.example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "orderId": "123",
  "status": "pending",
  "total": 99.99,
  "items": [
    { "productId": "A1", "quantity": 1 },
    { "productId": "B2", "quantity": 2 }
  ],
  "_links": {
    "self": { "href": "/orders/123" },
    "customer": { "href": "/customers/456" },
    "cancel": { "href": "/orders/123/cancel", "method": "POST" },
    "update": { "href": "/orders/123", "method": "PUT" }
  }
}

Example of a Level 3 RESTful API response with HATEOAS links. The _links object guides the client on possible next actions.