Stage 2. REST Essentials

REST is a practical way to design HTTP APIs so they stay understandable when the project grows. Its main idea is simple: model your API around resources and use HTTP semantics consistently. If this foundation is stable, documentation is shorter, integrations are faster, and maintenance cost is lower.

A resource is any domain object your system manages, for example books, users, orders, tasks. In REST, URL paths identify resources, and HTTP methods define what operation is requested for that resource.

Core REST model

A reliable design sequence is:

1. Define resource names as nouns.
2. Define collection and item paths.
3. Map operations to methods.
4. Define status codes and response format.

Basic resource map:

GET    /books
POST   /books
GET    /books/{id}
PUT    /books/{id}
DELETE /books/{id}

This pattern is repeatable across modules and creates a predictable API contract.

Principles that matter in real work

Resource-oriented design means the path tells what object you work with, not what command you execute. A route such as /books is resource-oriented. A route such as /createBook is command-oriented.

Stateless communication means each request contains enough context to be processed independently. The server should not depend on hidden UI state from previous calls.

Uniform interface means similar cases produce similar behavior. If two endpoints fail validation, both should return similar status class and similar error payload shape.

HTTP method semantics must stay clean: GET reads, POST creates, PUT replaces, DELETE removes.

Naming and URL structure

Use nouns in paths and avoid verbs in route names. Do not duplicate action meaning in URL if the method already defines it.

Avoid:

• /createBook
• /updateBook/12
• /deleteBook/12

Prefer:

• POST /books
• PUT /books/12
• DELETE /books/12

Collection paths are usually plural (/books), item paths include identifier (/books/{id}), and nested paths should be shallow and justified.

Path parameter vs query parameter

Use a path parameter when the value identifies one specific resource. Use query parameters when you filter, sort, search, or paginate a collection.

• GET /books/12 means “book with id 12”.
• GET /books?author=rowling means “books filtered by author”.
• GET /books?sort=title&page=2&size=20 means “books list with sorting and pagination”.

If a value is required to locate a single resource, it belongs in the path. If it changes list view options, it belongs in query string.

Status code discipline

Status codes are not decoration. They are a protocol-level signal for clients, logs, and monitoring.

Returning 200 for every case removes protocol meaning and makes clients harder to implement.

Response and error format consistency

For collection responses, object envelopes are usually easier to evolve than bare arrays. You can add metadata later without breaking consumers.

Example list response:

{
  "items": [
    { "id": 12, "title": "Clean Code" },
    { "id": 13, "title": "Refactoring" }
  ],
  "meta": {
    "page": 1,
    "size": 20,
    "total": 125
  }
}

Example error response:

{
  "error": "validation_failed",
  "message": "title is required",
  "details": [
    { "field": "title", "reason": "must not be blank" }
  ],
  "traceId": "a4f8d2e1"
}

A stable error shape makes frontend handling and support diagnostics much simpler.

Practical scenario: online library

Suppose your API manages books.

A user opens the catalog page. The client calls GET /books?page=1&size=20. The server returns a list envelope with items and meta.

The user adds a new book. The client sends POST /books with title and author. The server creates the record and returns 201 Created plus created object.

The user edits book 12. The client sends PUT /books/12 with full updated state. The server validates fields, updates the record, and returns 200 OK with updated object.

The user tries to open a removed book 99. The client sends GET /books/99. The server returns 404 Not Found with standard error format.

The user deletes book 12. The client sends DELETE /books/12. The server removes it and returns 204 No Content.

This one scenario covers the full REST baseline: resource paths, methods, status codes, list metadata, and consistent errors.

API versioning baseline

Versioning should be explicit from the beginning. A common approach is version in path, for example /api/v1/books.

Why this is useful: when you need breaking changes later, you can introduce /api/v2 without forcing every existing client to migrate immediately.

REST best practices checklist

• Use noun-based resource paths.
• Keep naming style consistent (lowercase, plural collections).
• Do not use verbs in URLs.
• Use methods according to HTTP semantics.
• Return meaningful status codes for each scenario.
• Keep response and error formats consistent.
• Use query parameters for filtering, sorting, and pagination.
• Keep URL nesting moderate.
• Add API version prefix before public growth.

Common mistakes to avoid

A frequent mistake is building RPC-like endpoints (/run, /execute, /process) for all operations. This hides resource model and complicates integrations.

Another mistake is inconsistent error handling, where one endpoint returns structured validation errors and another returns plain text. Client logic then becomes fragmented.

Another mistake is uncontrolled path growth, with deep routes for every relation. This reduces readability and increases coupling between client and server internals.

REST does not require a large framework to start correctly. It requires consistent decisions at API contract level. If you keep those decisions stable, the system stays easier to extend and support over time.