REST API Basics — Node.js Tutorial

What is a REST API?

REST (Representational State Transfer) is an architectural style for building web APIs. A REST API exposes resources (like users, products, posts) through URLs and uses HTTP methods to perform operations on them.

RESTful APIs are stateless — each request contains all the information needed to process it. The server does not store any client state between requests. This makes REST APIs scalable and easy to cache.

GET — Retrieve a resource or list of resources
POST — Create a new resource
PUT — Update an entire resource (replace)
PATCH — Partially update a resource
DELETE — Remove a resource

Example

// RESTful URL conventions for a 'users' resource:
//
// GET    /api/users       — Get all users
// GET    /api/users/42    — Get user with ID 42
// POST   /api/users       — Create a new user
// PUT    /api/users/42    — Update user 42 (full replace)
// PATCH  /api/users/42    — Partially update user 42
// DELETE /api/users/42    — Delete user 42

// Example JSON response:
{
  "status": "success",
  "data": {
    "id": 42,
    "name": "Alice",
    "email": "alice@example.com"
  }
}

Notes

REST APIs typically use JSON for request and response bodies. Always set Content-Type: application/json in your responses.

HTTP Status Codes

Status codes tell the client what happened with their request. Using the correct status codes is essential for a well-designed API. They are grouped into categories: 2xx for success, 4xx for client errors, and 5xx for server errors.

Always return the appropriate status code with every response. A 200 for a successful GET, 201 for a created resource, 404 when something is not found, and so on.

Example

const express = require('express');
const app = express();
app.use(express.json());

// 200 OK — Successful GET request
app.get('/api/users', (req, res) => {
  res.status(200).json({ users: [] });
});

// 201 Created — Resource successfully created
app.post('/api/users', (req, res) => {
  const user = { id: 1, ...req.body };
  res.status(201).json(user);
});

// 400 Bad Request — Invalid input
app.post('/api/login', (req, res) => {
  if (!req.body.email) {
    return res.status(400).json({ error: 'Email is required' });
  }
  res.json({ message: 'Logged in' });
});

// 404 Not Found
app.get('/api/users/:id', (req, res) => {
  const user = null; // not found in DB
  if (!user) {
    return res.status(404).json({ error: 'User not found' });
  }
  res.json(user);
});

200 OK — Request succeeded
201 Created — New resource created successfully
204 No Content — Success with no response body (used for DELETE)
400 Bad Request — Invalid input or missing required fields
401 Unauthorized — Authentication required
403 Forbidden — Authenticated but not authorized
404 Not Found — Resource does not exist
500 Internal Server Error — Unexpected server error

Notes

Use res.status(code).json(data) in Express to set the status code and send a JSON response in one line.