RESTful Services
A RESTful service is a web API designed around the principles of REST, short for Representational State Transfer. Instead of inventing a custom URL for every action, a REST API exposes resources, such as users, products or orders, at predictable URLs, and uses the standard HTTP methods to say what should happen to them. Most backends built with Node.js and Express for React frontends follow this style, so it is worth understanding before writing routes.
Resources and URLs
In REST, URLs name things, not actions. A collection lives at a plural noun, like /api/products, and a single item at the collection plus its ID, like /api/products/42. Related data can be nested one level, such as /api/users/7/orders. You avoid verbs in paths: /api/getProducts or /api/deleteProduct?id=42 are not RESTful, because the HTTP method already expresses the action.
Methods describe the action
| Method and path | Meaning | Typical success code |
|---|---|---|
GET /api/products | List products | 200 OK |
GET /api/products/42 | Read one product | 200 OK |
POST /api/products | Create a product | 201 Created |
PUT /api/products/42 | Replace the whole product | 200 OK |
PATCH /api/products/42 | Change some fields | 200 OK |
DELETE /api/products/42 | Remove it | 204 No Content |
GET must never change data. PUT and DELETE are expected to be idempotent: sending the same request twice leaves the server in the same state as sending it once. POST is not, since each call creates a new item.
Status codes and statelessness
A REST API reports outcomes with HTTP status codes rather than always answering 200 with an error inside the body. Clients rely on 404 for a missing item, 400 for invalid input, 401 when authentication is missing and 403 when the user lacks permission.
REST is also stateless: each request must carry everything the server needs to handle it, including the authentication token. The server does not remember earlier requests from that client. This makes the API easier to scale, because any server instance can handle any request.
A REST skeleton in Express
const router = require('express').Router();
router.get('/', listProducts); // GET /api/products
router.get('/:id', getProduct); // GET /api/products/:id
router.post('/', createProduct); // POST /api/products
router.patch('/:id', updateProduct); // PATCH /api/products/:id
router.delete('/:id', deleteProduct); // DELETE /api/products/:id
app.use('/api/products', router);
Filtering, sorting and pagination go in the query string, for example GET /api/products?category=books&page=2, rather than in new paths.
Responses should also follow a consistent shape. Return JSON objects with clear field names, and for errors use something predictable like { "error": "Product not found" }.
Where designs drift away from REST
A common anti-pattern is routing everything through POST, such as POST /api/products/delete. It works, but it throws away the benefits: caches cannot help with reads, tools cannot tell safe calls from dangerous ones, and other developers cannot guess your URLs. Another frequent issue is inconsistency, like mixing /api/product and /api/orders, or returning errors in different shapes from different routes. Pick conventions once and apply them everywhere.
In brief
Name resources with plural nouns, let HTTP methods express actions, answer with meaningful status codes, keep every request self-contained, and stay consistent across the whole API.
Ready to master real-world web development?
Learn HTML, CSS3, Bootstrap and JavaScript hands-on with mentor-led sessions.