شرح API Versioning في Laravel بسهولة للمطورين

لما تبني API، ممكن بعد فترة تحتاج تغير شكل الـ Response أو تضيف فيتشر جديدة. المشكلة إن في أبلكيشنز كتير بتستخدم الـ API القديم - لو غيرت بشكل فجائي هتبوّظهم. هنا بييجي دور API Versioning: يعني تحتفظ بأكتر من نسخة (Version) من الـ API قدامك، علشان التغييرات الجديدة متأثرش على الـ Clients اللي لسه مش قابلين التحديث.

الـ API Versioning مهم علشان:

• يحافظ على Backward Compatibility، يعني الـ Mobile App القديم يفضل يشتغل.
• يسهل إدارة التغيرات ويخلي لكل نسخة Docs خاصة.
• يخلي عملية migration للـ clients أبسط.
• يقلل الـ Risks خلال التطوير لأنك مش مربوط بنسخة واحدة.

أمتى تفكر تعمل Versioning؟ ​

لو عندك أي من الحالات دي:

• مستخدمين فعليين للـ API ولازم تضمن لهم استمرارية الخدمة.
• هتضيف فيتشر كبيرة أو تغير Response Schema.
• عايز تقدر تقدم نسخ مختلفة من الخدمة لعملاء مختلفين.
  لو أي حاجة من دي موجودة - ابدأ خطط للـ Versioning من الأول عشان توفر وجع الدم بعدين.

أشهر طريقتين لـ API Versioning (ونطبقهم في Laravel) ​

فيه طرق كتير، بس هنا هنركز على الطريقتين الشائعتين واللي كثير من الفرق بيستخدموهم:

1) URL Prefix Versioning (الأكتر شهرة)​

الفكرة بسيطة: تحط رقم النسخة جوه الـ URL كـ prefix، زي:

/api/v1/users
/api/v2/users

في Laravel تقدر تعمل ده بسهولة عن طريق Route::prefix جوا routes/api.php، أو تعمل ملف جديد لكل نسخة وتعمله require. مثال عملي:

ملف routes/api.php:

// api.php
require __DIR__ . '/api_v1.php';
require __DIR__ . '/api_v2.php';

ملف routes/api_v1.php:

Route::prefix('v1')->namespace('Api\V1')->group(function () {
    Route::get('users', 'UserController@index');
    Route::post('auth/login', 'AuthController@login');
});

ملف routes/api_v2.php:

Route::prefix('v2')->namespace('Api\V2')->group(function () {
    Route::get('users', 'UserController@index'); // ممكن يكون response مختلف
    Route::post('auth/login', 'AuthController@login');
});

وبكده كمان هتحافظ على File Structure منظمة: app/Http/Controllers/Api/V1 و app/Http/Controllers/Api/V2 - كل نسخة ليها Controllers و Resources و Requests خاصة بيها، وده بيساعدك وقت الصيانة.

2) Subdomain Versioning (لو تحب الـ DNS والتحكم الكبير) ​

بدل ما تحط النسخة في الـ path، بتحطها في الـ subdomain زي:

v1.api.example.com/users
v2.api.example.com/users

في Laravel تقدر تعمل ده باستخدام Route::domain أو حتى في Nginx/DNS تعمل الـ subdomains وتحط كل واحد يوجه للـ app.

مثال Laravel:

Route::domain('v1.api.example.com')->namespace('Api\V1')->group(function () {
    Route::get('users', 'UserController@index');
});
Route::domain('v2.api.example.com')->namespace('Api\V2')->group(function () {
    Route::get('users', 'UserController@index');
});

الـ Subdomain مفيد لو عايز تدي تحكم مستقل أو حتى تعمل انتشار (deploy) مختلف لكل نسخة. بس ليه متطلبات DNS وSSL مختلفة لكل subdomain - ففكر فيها.

طرق تانية شائعة (بس مش هنفصل فيها) ​

• Header Versioning: تبعت النسخة في Header زي Accept: application/vnd.myapp.v1+json. كويسة لو بتحب تبقي الـ URL نظيف، لكنها بتصعب الـ caching والـ testing شوية.
• Media Type Versioning: نفس فكرة الـ Header بس مع نوع ميديا.
  كل طريقة وليها مميزاتها وعيوبها - اختار المناسب لمشروعك.

أمثلة عملية وتنفيذ في Laravel (نقطة بخطوة) ​

1. ابدأ بمجلدات منفصلة لكل نسخة

app/Http/Controllers/Api/V1
app/Http/Controllers/Api/V2
resources/views/api/v1
resources/views/api/v2

1. اعمل Routes منفصلة زي ما شفنا في الأمثلة فوق - ويفضل تعمل ملف لكل نسخة علشان يكون الـ code مرتب.
2. Docs منفصلة لكل نسخة - استخدم Swagger أو Scribe وكل نسخة تولد docs خاصة بيها.
3. استخدم Resources/Transformers علشان لو الـ Response اتغير، تقدر تحتفظ بنفس الـ Response للنسخ القديمة والجديدة بسهولة.

خطوات عملية للـ Migration من نسخة لأخرى ​

• صدر نسخة جديدة مع Docs واضحة وRelease notes.
• خلي الـ clients يجربوا النسخة في بيئة Test أول.
• ادي فترة سماح (Deprecation period) قبل ما توقف الـ old version.
• استخدم Feature Flags لو التغيير كبير علشان تقدر ترجع بسهولة لو حصلت مشكلة.

أخطاء شائعة لازم تتجنبها ​

• تغيير الـ Response بشكل مفاجئ من غير Versioning.
• عدم توثيق التغييرات - الناس هتبقى ضايعة.
• ربط الـ Business Logic بقوة بين النسخ بدل ما تفصل Layers كويس.
• إهمال الأمن: كل نسخة محتاجة نفس سياسات الأمان (Auth, Rate limiting).

نصايح سريعة للمشاريع الحقيقية ​

• لو عندك مستخدمين خارجيين: اعمل Versioning من اليوم الأول.
• لو موظفينك بيستخدموا API داخلي: ممكن تبقى مرن أكتر، لكن برضه Versioning مفيد.
• خلي الـ version number واضح في الـ Docs والـ error messages.
• استخدم automated tests لكل نسخة.

خاتمة سريعة ​

الـ API Versioning مش رفاهية - ده أداة أساسية لأي مشروع API جاد. سواء باستخدام URL Prefix أو Subdomain، مهم جداً تحط قواعد واضحة، تنظم الملفات، وتوثق كل إصدار علشان المستخدمين مايوقفوش عن الشغل لما تغير حاجة.