Versionierung

Teil des Abschnitts REST-APIs der Node.js-Journey von Coddy. Lektion 15 von 18.

Eine Änderung der Antwortstruktur macht sie für jeden Client inkompatibel, der sie bereits verwendet. Eine Versionsnummer im Pfad ermöglicht es alten und neuen Clients, parallel zu existieren: heute /api/v1/orders, bei einer Änderung der Struktur /api/v2/orders. Bei verschobenen Pfaden wird eine Weiterleitung zurückgegeben:

GET  /api/orders/5   →  308  Location: /api/v1/orders/5
POST /api/orders     →  308  Location: /api/v1/orders

Bei 301 und 302 können Clients einen POST als GET wiederholen, wodurch der Body verloren geht. 308 bedeutet: „Wiederhole dort dieselbe Anfrage“, einschließlich Methode und Body. Innerhalb einer eingebundenen Middleware hat req.url den Mount-Pfad verloren, während req.originalUrl ihn vollständig beibehält:

// in app.use('/api/orders', ...) für GET /api/orders/5?full=1
req.url          // '/5?full=1'
req.originalUrl  // '/api/orders/5?full=1'

Aufgabe

Einfach

Binde den Tasks-Router unter /api/v1/tasks ein.
Jeder alte Pfad /api/tasks antwortet mit 308 und verweist auf denselben Pfad unter /api/v1, einschließlich Abfrageparametern.
Neue Tasks erhalten Location: /api/v1/tasks/<id>.

Sende GET /api/tasks/2, POST an /api/tasks mit { "title": "Order new chairs" } und anschließend GET /api/v1/tasks/2.

Probier es selbst

import express from 'express';
import { sendError } from './errors.js';
import taskRoutes from './routes/tasks.js';

const BOARD_ORIGIN = 'https://board.example.com';

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

// Ermöglicht Seiten auf BOARD_ORIGIN, diese API über den Browser aufzurufen.
app.use((req, res, next) => {
    res.set('Access-Control-Allow-Origin', BOARD_ORIGIN);
    res.set('Access-Control-Allow-Credentials', 'true');
    if (req.method === 'OPTIONS') {
        res.set('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE');
        res.set('Access-Control-Allow-Headers', 'Content-Type');
        return res.status(204).end();
    }
    next();
});

app.use(express.static('public'));

app.use('/api/tasks', taskRoutes);

// Fehler aus den Routen landen hier. Ein Body, der kein gültiges JSON enthält, ist ein
// Fehler des Clients (400); alles andere ist unser Fehler (500).
app.use((err, req, res, next) => {
    if (err.type === 'entity.parse.failed') {
        return sendError(res, 400, 'invalid_json', 'The body is not valid JSON');
    }
    console.error(err);
    sendError(res, 500, 'server_error', 'Something went wrong');
});

app.listen(3000, () => {
    console.log('Task tracker API on port 3000');
});