REST APIs

beginner2 min read

REST API
HTTP
Node.js
Express

A style for designing web APIs around resources, reusing HTTP methods and status codes so the interface is predictable and any client can consume it.

Prerequisites

HTTP request and response basics (see Related Topics)

What you'll understand

What makes an API RESTful
How resources, methods, and status codes combine into a predictable interface
Why REST APIs are easy to consume and evolve

Explanation

REST (Representational State Transfer) is a style for designing web APIs around resources, the nouns of your system such as users or orders. Each resource has a URL, and you act on it with HTTP methods: GET to read, POST to create, PUT or PATCH to update, DELETE to remove.

The power of REST is predictability. Once someone knows your resources, they can guess most of the API: GET /orders lists orders, GET /orders/7 reads one, POST /orders creates one. You reuse HTTP methods and status codes instead of inventing your own conventions, so any HTTP client can talk to your API.

REST APIs are stateless like HTTP itself: each request contains everything the server needs. Responses represent the resource, usually as JSON. Good REST design keeps URLs about resources (nouns), not actions (verbs), because the method already supplies the verb.

Examples

These routes show a conventional REST interface for an orders resource:

GET    /orders        list orders
POST   /orders        create an order
GET    /orders/7      read order 7
PATCH  /orders/7      update order 7
DELETE /orders/7      delete order 7

This TypeScript example defines two of those routes with Express and returns accurate status codes:

app.get('/orders/:id', async (req, res) => {
  const order = await orders.findById(req.params.id);
  if (!order) return res.status(404).json({ message: 'Not found' });
  res.json(order);
});

app.post('/orders', async (req, res) => {
  const created = await orders.create(req.body);
  res.status(201).json(created);
});

Common mistakes

Putting verbs in URLs such as /getOrder or /createOrder. Let the HTTP method be the verb and keep URLs as resource nouns.
Returning 200 for everything, including errors. Use 201 for created, 404 for missing, 400 for bad input.
Nesting resources too deeply. Keep paths shallow and predictable.
Returning raw database shapes; expose a stable representation you control.

Best practices

Model resources as nouns and use methods for actions.
Use consistent, plural resource names and predictable paths.
Return the right status code and a small, consistent error shape.
Validate input at the boundary before touching your data (see Related Topics).