ניהול גרסאות

חלק מהיחידה REST APIs במסלול ה-Node.js של Coddy. שיעור 15 מתוך 18.

שינוי הצורה של תשובה שובר כל לקוח שכבר משתמש בה. גרסה בנתיב מאפשרת ללקוחות ישנים וחדשים לפעול זה לצד זה: /api/v1/orders היום, /api/v2/orders כשהצורה משתנה. נתיבים שעוברים למקום אחר משיבים בהפניה:

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

הפניות 301 ו־302 מאפשרות ללקוחות לחזור על בקשת POST כבקשת GET, וכך הגוף שלה אובד. 308 אומר "חזור על אותה בקשה שם", כולל השיטה והגוף. בתוך תוכנת ביניים שמחוברת לנתיב, req.url כבר לא כולל את נתיב החיבור, ואילו req.originalUrl שומר את כולו:

// ב־app.use('/api/orders', ...) עבור GET /api/orders/5?full=1
req.url          // '/5?full=1'
req.originalUrl  // '/api/orders/5?full=1'

אתגר

קל

חברו את נתב המשימות בכתובת /api/v1/tasks.
כל נתיב ישן של /api/tasks משיב בהפניה 308 לאותו נתיב תחת /api/v1, כולל השאילתה.
משימות חדשות מקבלות Location: /api/v1/tasks/<id>.

שלחו GET /api/tasks/2, בקשת POST אל /api/tasks עם { "title": "Order new chairs" }, ואז GET /api/v1/tasks/2.

נסו בעצמכם

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());

// מאפשר לדפים ב-BOARD_ORIGIN לקרוא ל-API הזה מהדפדפן.
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);

// שגיאות מהנתיבים מגיעות לכאן. גוף בקשה שאינו JSON תקין הוא
// טעות של הלקוח (400); כל שגיאה אחרת היא באחריותנו (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');
});