Pemberian Versi

Termasuk bagian REST API dalam perjalanan Node.js di Coddy. Pelajaran 15 dari 18.

Mengubah bentuk respons akan merusak semua client yang sudah menggunakannya. Versi di path memungkinkan client lama dan baru berjalan berdampingan: /api/v1/orders saat ini, /api/v2/orders saat bentuknya berubah. Path yang dipindahkan memberikan respons pengalihan:

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

Respons 301 dan 302 memungkinkan client mengulangi POST sebagai GET, sehingga body terbuang. 308 berarti "ulangi permintaan yang sama di sana", termasuk method dan body. Di dalam middleware yang dipasang, req.url tidak lagi menyertakan path pemasangan, sedangkan req.originalUrl tetap menyimpan semuanya:

// di app.use('/api/orders', ...) untuk GET /api/orders/5?full=1
req.url          // '/5?full=1'
req.originalUrl  // '/api/orders/5?full=1'

Tantangan

Mudah

Pasang router tasks di /api/v1/tasks.
Setiap path lama /api/tasks mengembalikan 308 ke path yang sama di bawah /api/v1, termasuk query.
Task baru mendapatkan Location: /api/v1/tasks/<id>.

Kirim GET /api/tasks/2, POST /api/tasks dengan { "title": "Order new chairs" }, lalu GET /api/v1/tasks/2.

Coba sendiri

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

// Memungkinkan halaman di BOARD_ORIGIN memanggil API ini dari browser.
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);

// Error dari routes ditangani di sini. Body yang bukan JSON valid adalah
// kesalahan client (400); selebihnya adalah kesalahan server kita (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');
});