Tech Notes

REST – Resource-Oriented API Design

4 min read

REST in the Application Layer

When systems talk to other systems (not browsers), they usually do so via APIs.

There are three major API paradigms:

  • REST
  • GraphQL
  • gRPC

Among these, REST is the default and most common choice, especially in system design interviews.

Summary

REST is a simple, flexible way to expose application functionality over HTTP using resource-based thinking.

Core Idea of REST

REST stands for Representational State Transfer.

The key idea:

  • systems expose resources
  • clients perform standard operations on those resources

Think of resources like:

  • Database tables
  • Files on a server
  • Domain entities

Analogy:
REST treats your system like a remote file system where you read, create, update, and delete files using standard commands.

Resources, Not Actions (Very Important)

REST forces a mindset shift.

Bad (action-based thinking):

  • updateUser
  • startGame
  • cancelOrder

Good (resource-based thinking):

  • User
  • Game
  • Order

Operations are expressed using HTTP verbs, not method names.

Important

REST models nouns (resources), not verbs (actions).

Mapping REST to HTTP

REST uses:

  • HTTP methods to express intent
  • URL paths to identify resources
  • request/response bodies to represent resource state

This reuse of HTTP semantics is what makes REST simple and powerful.

Basic REST Patterns (CRUD)

Assume User is a JSON object.

Read a resource

GET /users/{id} → User
  • GET = fetch
  • {id} = resource identifier
  • no request body

Update an existing resource

PUT /users/{id} → User
    {
      "username": "john.doe",
      "email": "john.doe@example.com"
    }
  • PUT = replace/update resource
  • resource already exists
  • client sends new representation

Important

PUT is typically idempotent (same request → same result).

Create a new resource

POST /users → User
    {
      "username": "stefan.mai",
      "email": "stefan@hellointerview.com"
    }
  • POST = create
  • server assigns the ID
  • client does not specify {id}

Delete a resource

DELETE /users/{id}
  • DELETE = remove resource
  • should be idempotent

Nested Resources (Relationships)

REST can express relationships through path nesting.

Example:

  • one user

  • many posts

    GET /users/{id}/posts → [Post]

This communicates:

  • ownership
  • hierarchy
  • containment

Summary

Path structure explains relationships between resources.

REST and Domain Modeling

In system design:

  • your core entities often map directly to REST resources
  • this makes APIs intuitive and consistent

Example:

  • User entity → /users
  • Order entity → /orders
  • Product entity → /products

Tip

If your domain model is clean, your REST API usually designs itself.

REST Conventions (Not Strict Rules)

REST is opinionated, not rigid.

Common conventions:

  • JSON for request/response bodies
  • plural nouns for collections
  • predictable paths
  • meaningful HTTP status codes

But:

  • REST does not require JSON
  • REST does not enforce one “correct” structure

What REST is NOT

REST is often misunderstood.

Not RESTful:

  • POST /updateUser
  • POST /startGame
  • GET /doPayment

These describe actions, not resources.

RESTful alternatives:

  • PUT /users/{id}
  • PATCH /games/{id} { “status”: “started” }
  • POST /payments

Warning

If your API reads like function calls, it’s probably not RESTful.

Performance Considerations

REST tradeoffs:

  • JSON is verbose
  • serialization/deserialization costs CPU
  • not ideal for extremely high throughput systems

However:

  • most systems are not bottlenecked here
  • simplicity usually wins

Summary

REST optimizes for clarity and flexibility, not raw performance.

Where REST Shines

REST works well for:

  • CRUD-heavy systems
  • public APIs
  • internal microservices
  • admin and configuration APIs

Real-world example:

  • ElasticSearch uses REST to manage documents, indexes, and clusters

Where REST Struggles

REST may not be ideal for:

  • real-time streaming
  • bi-directional communication
  • very low-latency, high-throughput systems

Alternatives:

  • GraphQL → flexible querying
  • gRPC → high-performance RPC
  • WebSockets / SSE → realtime updates

REST in System Design

Why REST is the default:

  • well understood
  • easy to reason about
  • maps cleanly to HTTP
  • widely adopted

Interview guidance:

  • default to REST
  • switch only if requirements demand it

Important

Like TCP, REST is a safe and expected default in interviews.

Mental Model for Revision

  • REST = resource-oriented design
  • URLs identify resources
  • HTTP verbs express intent
  • JSON represents state
  • stateless by default
  • scalable by design

Summary

REST is about modeling your system as resources and using HTTP correctly to operate on them.

Graph View