What is REST – RESTful API Fundamentals for Java Developers

Direct Answer

REST (Representational State Transfer) is an architectural style for client-server systems. An API is RESTful when its interactions follow REST's mandatory constraints, including stateless requests, responses that declare their cache rules, a uniform interface, and layered components. Code-on-demand is optional. Using HTTP and returning JSON is common, but those choices alone do not make an API RESTful.

Deep Dive & Architecture

The plain meaning

REST describes how parts of a networked application communicate. It does not tell us which Java framework to use or which database to choose. Instead, it limits the way components interact so that clients, servers, and intermediaries can understand the same messages and change independently.

The six constraints

• Client-server: the client deals with the user experience, while the server owns resources and business work. Each side can change without knowing the other's internal code.
• Stateless: every request contains the context needed to understand it. The server does not rely on a hidden conversation from an earlier request.
• Cache: every response says whether it may be reused and, when allowed, under which rules. Correct caching can reduce repeated work and network traffic.
• Uniform interface: resources and messages follow shared rules instead of a private command language for every endpoint.
• Layered system: a client can communicate through a gateway, proxy, or cache without needing to know the full path to the origin server.
• Code-on-demand: a server may send executable code that extends a client. This is the only optional constraint.

The four parts of the uniform interface

1. Identify resources: a URI identifies the resource involved in an interaction.
2. Manipulate resources through representations: a client sends a representation of the state it wants or receives a representation of the current state.
3. Use self-descriptive messages: the method, status, headers, media type, and message rules provide enough meaning to process the message.
4. Use hypermedia for next actions: a representation can include controls that tell the client which transitions are available from the current state.

An order as a REST resource

The URI /orders/42 identifies an order resource. A response to GET /orders/42 transfers a representation of that order and uses HTTP metadata to explain the result. The method gives the request meaning, the status code gives the outcome, Content-Type describes the representation, and cache fields describe reuse. Links can identify valid next actions. None of this requires the client to know the server's controller class or table name.

Where “REST API” becomes imprecise

Using HTTP methods, noun-based paths, and JSON is a useful start, but it is not the complete REST definition. In particular, REST's uniform interface includes hypermedia: the response can tell the client what it may do next. Many practical APIs adopt only part of this style. That can be a sensible engineering choice, but “REST-style HTTP API” is a more precise name when important constraints are intentionally missing.

Code Example

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: private, max-age=60
ETag: "order-v7"

{
  "id": 42,
  "status": "pending",
  "total": 1999,
  "links": [
    {"rel": "self", "href": "/orders/42"},
    {"rel": "cancel", "href": "/orders/42/cancellation"}
  ]
}

HTTP gives standard meaning to the status, Content-Type, cache rule, and opaque ETag validator. The JSON field names and link relations are application-defined, so application/json alone does not explain their meaning; the API still needs a documented contract or a media type that defines those semantics.