Uniform Interface

Identification of resources, HATEOAS

“The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components.” – Roy Fielding

When to use

Designing the API contract.

Why it matters

  • Decoupling: The implementation can change, but the interface stays the same.
  • Discoverability: Standard methods (GET, POST, PUT, DELETE) mean developers can guess how to use your API.

Signs of Violation

  • RPC style URLs: /getUser, /updateUser, /deleteUser.
  • Returning different error formats for different endpoints.
  • Ignoring HTTP status codes (Sending 200 OK for an error).

Explanation

Problem

If every API invents its own language, clients must be custom-built for every API.

Solution

  1. Resource Identification: URI (/users/1).
  2. Resource Manipulation: HTTP Verbs (GET, PUT).
  3. Self-descriptive messages: Content-Type (application/json).
  4. HATEOAS: Hypermedia as the Engine of Application State (Links in the response).

Real world analogy

USB Standard. You can plug a mouse, a keyboard, or a fan into a USB port. The interface (Shape + Protocol) is uniform. You don’t need a specific shape of hole for a mouse.

Pros and Cons

Pros Cons
  • Standardization
  • Evolvability
    		•
  • HATEOAS is hard to implement fully
    		•

    Comparison

    • RPC (Remote Procedure Call): Focuses on actions (deleteUser), REST focuses on resources (DELETE /users/1).

    Code example

    Typescript

    Bad (Violation)

    Good (Adherence)

    PHP

    Bad (Violation)

    Good (Adherence)