Sürümleme

Coddy'nin Node.js Journey'sinin REST API'leri bölümünün bir parçası. Ders 22 / 25.

Bir yanıtın biçimini değiştirmek, onu zaten kullanan tüm istemcileri bozar. Yoldaki bir sürüm, eski ve yeni istemcilerin yan yana çalışmasını sağlar: bugün /api/v1/orders, biçim değiştiğinde /api/v2/orders. Bir yol değiştiğinde eski yol, yeni yola yönlendirme yanıtı verir:

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

301 ve 302, istemcilerin bir POST isteğini GET olarak yinelemesine izin verir; bu da gövdenin kaybolmasına neden olur. 308, yöntem ve gövde dâhil olmak üzere "aynı isteği oraya yinele" anlamına gelir. Bağlanmış bir ara yazılımın içinde req.url bağlanma yolunu kaybetmişken req.originalUrl yolun tamamını korur:

// GET /api/orders/5?full=1 için app.use('/api/orders', ...) içinde
req.url          // '/5?full=1'
req.originalUrl  // '/api/orders/5?full=1'

Görev

Kolay

API'niz eski istemcilerin beklemediği şekillerde değişeceğinden, yollarına bir sürüm numarası ekleyin. Bugünkü API, /api/v1/tasks adresinde 1. sürüm olur ve eski adresler istemcileri buraya yönlendirir.

server.js dosyasında tasks yönlendiricisini /api/tasks yerine /api/v1/tasks adresine bağlayın.
Ayrıca server.js dosyasında, yalnızca yönlendirme yapan ve /api/tasks adresine bağlanan bir ara katman yazılımı ekleyin. Yanıt olarak, yolun geri kalanını ve sorgu dizesini koruyarak aynı adresin /api/v1 altındaki karşılığına 308 durum koduyla yönlendirme yapar. Bağlanmış bir ara katman yazılımının içinde req.originalUrl, eski adresin tamamını içerir. Örneğin:
- GET /api/tasks/2, /api/v1/tasks/2 adresine yönlendirilir.
- POST /api/tasks, /api/v1/tasks adresine yönlendirilir.
- GET /api/tasks?done=false&sort=title, /api/v1/tasks?done=false&sort=title adresine yönlendirilir.
301 yerine 308 kullanın: 308 durum kodundan sonra istemci, gövde de dâhil olmak üzere, POST isteğini yine POST olarak yineler.
routes/tasks.js dosyasında POST rotası, Location değerini yeni adrese ayarlar; örneğin 4. görev için /api/v1/tasks/4.

Deneyin: GET /api/tasks/2, 308 döndürür ve Başlıklar sekmesinde Location: /api/v1/tasks/2 görünür. İstek çubuğu yönlendirmenin kendisini gösterir; yönlendirmeyi takip etmez. { "title": "Order new chairs" } gövdesini /api/tasks adresine POST olarak gönderin: Location: /api/v1/tasks ile birlikte 308 alırsınız ve hiçbir görev oluşturulmaz. Aynı gövdeyi /api/v1/tasks adresine POST olarak gönderin: Location: /api/v1/tasks/4 ile birlikte 201 alırsınız. GET /api/v1/tasks/2, 2. görevi döndürür.

Kendin dene

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

// BOARD_ORIGIN üzerindeki sayfaların tarayıcıdan bu API'yi çağırmasına izin verir.
app.use((req, res, next) => {
    res.set('Access-Control-Allow-Origin', BOARD_ORIGIN);

    if (req.method === 'OPTIONS') {
        res.set('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
        res.set('Access-Control-Allow-Headers', 'Content-Type');
        return res.status(204).end();
    }
    next();
});

app.use(express.json());

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

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

// Rotalardan gelen hatalar burada ele alınır. Geçerli JSON olmayan bir gövde,
// istemcinin hatasıdır (400); diğer tüm hatalar bize aittir (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');
});