REST in plain language
A REST API is a way to expose data and actions on the web by treating them as resources that can be addressed with URLs. The method you choose (GET, POST, PATCH, DELETE) expresses what you want to do with that resource. The idea is to reuse the web’s built-in rules instead of creating a custom protocol.
This makes APIs easier to understand and easier to integrate. Developers can often guess how an endpoint behaves because it follows common web conventions. That predictability is the real value of REST: it reduces cognitive load and makes tooling work out of the box.
Resources: the core model
In REST, everything meaningful becomes a resource: a user, a device, an order, a log entry, a report. Each resource has a stable URL. For example, `/users/123` refers to one user, while `/orders/987` points to a single order.
A resource is not the same as a database row. You can expose a computed report as a resource, or represent a workflow state as a resource. The key is that the resource has identity and can be addressed consistently.
HTTP verbs are your action grammar
REST APIs use HTTP verbs to express intent. `GET` reads data, `POST` creates, `PUT` replaces, `PATCH` updates partially, and `DELETE` removes. These verbs are understood by caches, proxies, and debugging tools, which is why REST integrates well with the web ecosystem.
Avoid encoding actions in the URL such as `/users/123/delete`. Instead, keep the URL for the resource and use the verb: `DELETE /users/123`. This leads to a consistent and scalable API surface.
Statelessness: requests stand alone
Statelessness means the server does not keep hidden session state between requests. Each call includes the context needed to process it. This makes horizontal scaling easier and reduces bugs caused by inconsistent server state.
Clients can keep their own state (tokens, cached responses), but the server should not depend on past requests. When in doubt, include explicit identifiers and avoid hidden server-side sessions.
Representation vs resource
A resource can have different representations. Today you may return JSON; tomorrow you may return a more compact format or a different schema for a particular client. REST allows this flexibility because the resource identity stays the same.
A good API response is designed for consumers, not for the database. Hiding internal structures gives you freedom to evolve your storage and logic without breaking clients.
Consistency beats cleverness
The biggest advantage of REST is consistency. When every resource follows the same rules, integrations become fast and predictable. Consistency also makes documentation simpler because the same patterns repeat.
Resist the urge to create one-off exceptions. A few exceptions quickly become an unpredictable API that is hard to maintain and easy to misuse.
REST in real systems
Most production APIs are pragmatic. They may use POST for advanced searches, expose a few action endpoints, or simplify certain constraints for performance. That is normal and often necessary.
The rule is not purity; the rule is clarity. If you deviate from classic REST, do it deliberately and document it.
A quick example
Imagine a home automation API. You might expose `/devices` to list devices, `/devices/42` to get a single device, and `/devices/42/state` to read or update state. Clients use `GET` for reading and `PATCH` for updates.
This model is simple, but powerful. A developer can guess new endpoints without reading pages of documentation. That is what REST gives you: intuitive structure.
When REST is not ideal
Some problems are not resource-centric. Streaming data, complex command workflows, or real-time collaboration may be better suited to WebSockets, event streams, or RPC.
REST is an excellent default for CRUD and resource access, but it is not the only pattern. Use it where it fits and complement it where it doesn’t.
A simple mental checklist
If you can name the key objects in your system and treat them as resources, REST is likely a good fit. If your API feels like a sequence of commands rather than objects, consider RPC or event-based approaches.
Most teams start with REST because it is easy to understand and easy to evolve. You can always add other styles later as needs grow.