API بدون نسخة: متى تنقلب سهولة البداية إلى ثمن لا ينتهي؟

في مشروع تطبيق جوّال + API Laravel، قررت تجاهل versioning في البداية. المبرر كان عملياً: التطبيق المحلي، المستخدمون يُحدَّثون تلقائياً، ولا وقت لبنية زائدة. كل شيء تحت /api/. بعد سنة من الإنتاج، احتجت تغيير شكل response لـ /api/orders ليشمل بيانات إضافية بترتيب مختلف.

اكتشفت أن 30% من المستخدمين لا يزالون على إصدار قديم من التطبيق لم يُحدَّثوا — سواء لأن التحديث التلقائي أُوقف على أجهزتهم أو لأسباب شبكة. أي تغيير في الـ response كسر التطبيق القديم. التراجع عن التغيير كسر الـ feature الجديدة.

الجوهر: الحل الذي طبّقته لم يكن إعادة بناء كاملة. أضفت /api/v2/ لفقط الـ endpoints التي تغيّرت، وأبقيت /api/ يشير لنفس controllers القديمة حتى انتهاء دعم الإصدار القديم. ليس نظيفاً تماماً، لكنه سمح بالتطور دون كسر.

// routes/api.php
Route::prefix('v2')->group(function () {
    Route::apiResource('orders', V2\OrderController::class);
});
// v1 يبقى كما هو حتى sunset
Route::apiResource('orders', V1\OrderController::class);

ما تغيّر في طريقة تفكيري: versioning ليس بنية تحتية للمستقبل — هو عقد صريح مع المستخدم الحالي يقول «هذا الشكل سيبقى حتى نخبرك». الـ URL بدون نسخة يعني ضمنياً «قد يتغير هذا». المستخدم لا يعرف ذلك إلا حين يُكسر.