REST API

Roy Fielding defined REST in 2000 in his dissertation Architectural Styles and the Design of Network-based Software Architectures at the University of California, Irvine. He worked as an editor on the HTTP/1.1 specifications and developed REST in parallel with that standard. The architectural style is not a protocol, but a collection of principles for communication between systems over a network.

2. Use HTTP methods as building blocks

REST uses existing HTTP methods: `GET` retrieves data, `POST` creates a new resource, `PUT` modifies an existing resource, and `DELETE` removes a resource. These methods are defined in RFC 7231, published by the IETF in June 2014. The methods are either safe (they change nothing, like `GET`) or idempotent (repeated execution gives the same result, like `PUT` and `DELETE`).

3. Handle stateless communication

Each request from a client to a server contains all the information needed to process that request. The server does not remember state between requests. This simplifies the server side because no session state needs to be maintained, and makes horizontal scaling easy: each request can be forwarded to any available server without transferring context.

4. Identify resources with URIs

Each resource — a user, product, or order — has a unique URI. The client communicates with this resource via HTTP methods. A `GET` request retrieves data, a `POST` creates a new resource. This consistent approach makes REST simple to implement and contributes to the uniformity of web APIs.

5. Work with JSON and process it with jq

RESTful APIs usually use JSON as the data format. JSON is lightweight and works well with JavaScript. Use `jq` to filter and aggregate JSON responses. For example, to calculate the sum of prices from a product list:

curl -s https://api.example.com/products | jq 'map(.price) | add'

This command retrieves the product list, extracts all prices, and adds them up.

6. Build a REST API with Node.js

Node.js is a server-side JavaScript runtime that works asynchronously and efficiently handles many concurrent requests. This aligns well with the stateless nature of REST. A simple API listens on HTTP, exposes resources via URLs, and returns JSON responses. Use Express 4.18 or higher for routing:

npm init -y
   npm install express

Create a file `server.js`:

const express = require('express');
   const app = express();
   app.use(express.json());</p><p>const products = [{ id: 1, name: 'Laptop', price: 999 }];</p><p>app.get('/products', (req, res) => {
     res.json(products);
   });</p><p>app.post('/products', (req, res) => {
     const product = { id: products.length + 1, ...req.body };
     products.push(product);
     res.status(201).json(product);
   });</p><p>app.listen(3000, () => console.log('API listening on port 3000'));

Start the server with `node server.js`.

7. Consult an existing REST API

The BelgicaPress API provides access to digitized Belgian newspapers from 1800–1970. Via HTTP requests, you can retrieve articles by keyword, date, newspaper title, or region. The API also supports IIIF (International Image Interoperability Framework) for high-resolution imagery. This shows that REST not only delivers textual data, but also media files such as scans of historical newspapers.

Europeana Newspapers also offers a REST API for cultural heritage. Users get access to newspaper articles from various countries, including Belgium, via a free API key. Authentication via an API key is a common method in REST APIs to manage access without full user accounts.

8. Recognize the limitations of REST

Many so-called REST APIs do not meet all the principles of REST, particularly the requirement to use hypermedia (HATEOAS, Hypermedia as the Engine of Application State). A strictly RESTful system returns, alongside data, links that indicate which actions are possible, so the client can navigate the API dynamically. APIs that do not do this are sometimes called "REST-like" or "HTTP APIs." Nevertheless, the term REST remains widely used for APIs that apply HTTP methods and status codes in a structured manner.

Verification

curl http://localhost:3000/products

This returns the list of products in JSON format. Create a new product:

curl -X POST http://localhost:3000/products \
  -H "Content-Type: application/json" \
  -d '{"name":"Monitor","price":299}'

Then check whether the product is in the list:

curl http://localhost:3000/products | jq '.[] | select(.name=="Monitor")'

Frequently Asked Questions

Add CORS headers to your Express server:

npm install cors

const cors = require('cors');
   app.use(cors());

2. JSON parse error when sending a POST request

Make sure the Content-Type header is correctly set to `application/json` and that the body contains valid JSON. Check with `jq` whether the JSON is valid:

echo '{"name":"Test"}' | jq .

3. API returns 404 for a valid URI

Check whether the route exactly matches the URI in your Express app. Express routes are case-sensitive and match on the full path. Use `app.get('/products/:id')` for dynamic routes. ```