Summarize this content to 400 words in Persian Lang در چشم انداز توسعه امروزی، API ها ستون فقرات بسیاری از برنامه ها هستند و امکان ادغام در سیستم های مختلف را فراهم می کنند.
همانطور که الزامات و ویژگی‌ها تکامل می‌یابند، نسخه‌سازی API برای حفظ سازگاری به عقب ضروری می‌شود و تضمین می‌کند که مشتریان موجود همانطور که انتظار می‌رود به کار خود ادامه می‌دهند در حالی که نسخه‌های جدید عملکردهای پیشرفته‌تری را معرفی می‌کنند.
پس زمینه: از دینگو API تا نسخه Laravel API
از لحاظ تاریخی، من به بسته محبوب دینگو API برای پروژه‌های مبتنی بر لاراول، به ویژه برای مدیریت نسخه‌سازی API، متکی بوده‌ام.
دینگو API مدتهاست که یک راه حل قابل اعتماد برای مدیریت نسخه ها و ارائه سایر ابزارهای خاص API در لاراول بوده است.
با این حال، با تکامل لاراول و اکوسیستم آن، نیاز به یک راه حل ساده تر و هدفمندتر نیز افزایش یافت. نسخه API لاراول فقط این را ارائه می دهد: یک بسته متمرکز و آسان برای پیاده سازی برای مدیریت نسخه، بدون سربار اضافی از ویژگی هایی که ممکن است به آن نیاز نداشته باشید.
علاوه بر این، نسخه API لاراول بسته از رویکرد GitHub به نسخه API الهام گرفته است. نسخه REST API GitHub از ترکیبی از هدرهای سفارشی و Accept هدرها برای مشخص کردن نسخه‌ها، که رویکردی تمیز و انعطاف‌پذیر را ارائه می‌دهد که URLها را ثابت نگه می‌دارد و در عین حال امکان کنترل نسخه را فراهم می‌کند.
با نسخه Laravel API، می‌توانید از یک استراتژی مشابه مبتنی بر هدر استفاده کنید یا کنترل نسخه صریح را در مسیرهای خود انتخاب کنید.
آشنایی با استراتژی های نسخه سازی API
انتخاب استراتژی نسخه سازی مناسب برای API شما بسیار مهم است. در اینجا نگاهی به رایج ترین استراتژی ها، همراه با مزایا و معایب آنها می اندازیم:
استراتژی
توضیحات
جوانب مثبت
منفی
نسخه URI
نسخه API در مسیر URL مشخص شده است، به عنوان مثال، https://api.example.com/v1/resource
– اجرای ساده و آسان- پاک کردن نسخه در URL
– صلبیت URL (تغییر نسخه بر ساختار URL تأثیر می گذارد)- آرامش کمتری دارد زیرا URL ها معمولاً فقط برای منابع هستند
نسخه پرس و جو پارامتر
نسخه به عنوان پارامتر پرس و جو اضافه می شود، به عنوان مثال، https://api.example.com/resource?version=1
– URL قابل انعطاف- URL پایه ثابت می ماند
– URL را با پارامترها به هم می زند- در API های REST کمتر رایج است
نسخه‌سازی مبتنی بر سربرگ
نسخه به صورت سرصفحه ارسال می شود، به عنوان مثال، Accept: application/vnd.example+v1+json یا X-API-Version: 1، با الهام از رویکرد GitHub
– URL های تمیز (بدون نسخه در URL)- کنترل نسخه قابل انعطاف
– مشتریان باید هدرها را به درستی تنظیم کنند، که می تواند پیچیدگی را اضافه کند- نسخه در URL قابل مشاهده نیست
کنترل نسخه صریح
نسخه مستقیماً در کد مشخص شده است، بنابراین کلاینت ها نسخه را کنترل نمی کنند که برای API های داخلی ایده آل است
– کنترل کامل بر نسخه سازی- به پیکربندی مشتری متکی نیست
– محدود کننده، برای API های عمومی مناسب نیست- نیاز به نگهداری مسیر برای هر نسخه
هر استراتژی دارای نقاط قوت و مبادلات منحصر به فردی است، بنابراین ضروری است که یکی را انتخاب کنید که با نیازها و الگوهای استفاده API شما هماهنگ باشد.
چرا نسخه API لاراول را انتخاب کنید؟
نسخه API لاراول طراحی شده است تا نسخه API در برنامه های لاراول را آسان و انعطاف پذیر کند. این بر روی یک رویکرد ساده برای مسیریابی درخواست‌ها به کنترل‌کننده نسخه صحیح با استفاده از یکی از موارد زیر تمرکز دارد:
تشخیص نسخه مبتنی بر سربرگ: ایده آل برای API های عمومی که در آن مشتریان می توانند نسخه را از طریق هدرها مشخص کنند.
کنترل صریح نسخه: نسخه ها را مستقیماً در مسیرها یا گروه های مسیر مشخص کنید، مناسب برای API های داخلی یا کاملاً کنترل شده.
با نسخه Laravel API، می توانید:
شناسایی و مسیریابی درخواست ها بر اساس Accept هدرها یا هدرهای سفارشی
صراحتاً نسخه‌ها را در هر مسیر یا گروه مسیر مشخص کنید، با عبور از تشخیص هدر.
فضاهای نام قابل تنظیم را برای کنترلرهای نسخه شده تعریف کنید.
چندین نسخه API را بدون مسیرها یا کنترلرهای به هم ریخته مدیریت کنید.
شروع به کار با نسخه API لاراول
در اینجا یک راهنمای سریع برای نصب و پیکربندی Laravel API Version آورده شده است.
مرحله 1: بسته را نصب کنید
بسته را از طریق Composer نصب کنید:
composer require cleaniquecoders/laravel-api-version
مرحله 2: فایل پیکربندی را منتشر کنید
برای سفارشی کردن بسته، فایل پیکربندی آن را با دستور زیر منتشر کنید:
php artisan vendor:publish –tag=”laravel-api-version-config”
این یک ایجاد خواهد کرد config/api-version.php فایل در این فایل می‌توانید نسخه پیش‌فرض را تنظیم کنید، هدرها را سفارشی کنید، فضای نام ریشه را پیکربندی کنید و موارد دیگر.
پیکربندی نمونه
در اینجا نگاهی اجمالی به فایل پیکربندی پیش فرض داریم:
return [
‘default_version’ => ‘v1’,
‘use_accept_header’ => true,
‘custom_header’ => ‘X-API-Version’,
‘accept_header_pattern’ => ‘/application\/vnd\.\w+\+v(\d+(\.\d+)*)\+json/’,
‘root_namespace’ => ‘App\Http\Controllers\Api’,
];
تنظیمات کلیدی عبارتند از:
default_version: اگر نسخه ای مشخص نشده باشد، نسخه پیش فرض API استفاده می شود.
use_accept_header: برای شناسایی نسخه ها از Accept هدر
custom_header: یک هدر سفارشی برای نسخه‌سازی تنظیم کنید (پیش‌فرض است X-API-Version).
root_namespace: فضای نام پایه را برای کنترلرهای نسخه شده تعریف کنید.
مرحله 3: تعریف مسیرهای نسخه شده
Laravel API نسخه ارائه می دهد api.version میان افزاری که از قبل هنگام نصب این بسته پیکربندی شده است و به شما امکان می دهد مسیرهای نسخه شده را به راحتی تعریف کنید.
گزینه 1: تشخیص نسخه مبتنی بر سربرگ
برای فعال کردن تشخیص خودکار نسخه از هدرها، از api.version میان افزار در مسیرهای شما میان‌افزار نسخه‌ها را از هر کدام شناسایی می‌کند Accept یا X-API-Version هدرها و به صورت پویا درخواست ها را به فضای نام نسخه شده صحیح هدایت می کند.
در routes/api.php:
use Illuminate\Support\Facades\Route;
Route::middleware([‘api’, ‘api.version’])->group(function () {
Route::get(‘/example’, ‘ExampleController@index’);
// Add other routes for this version
});
با این تنظیمات، درخواست ها می توانند نسخه را از طریق سرصفحه هایی مانند:
Accept هدر: Accept: application/vnd.yourapp+v2+json
هدر سفارشی: X-API-Version: 2
گزینه 2: تنظیم صریح نسخه
اگر ترجیح می دهید نسخه را مستقیماً در مسیرها مشخص کنید، با عبور از تشخیص هدر، نسخه را به عنوان پارامتر به میان افزار ارسال کنید:
Route::middleware([‘api’, ‘api.version:v2’])->group(function () {
Route::get(‘/example’, ‘ExampleController@index’);
// Additional routes for version 2
});
با تعریف api.version:v2، تمام مسیرهای این گروه بدون توجه به هدرها به فضای نام نسخه 2 هدایت می شوند.
نمونه درخواست ها
در اینجا نحوه فراخوانی API نسخه شده خود با استفاده از نسخه Laravel API آورده شده است.
با استفاده از Accept سربرگ:
curl -L -H “Accept: application/vnd.yourapp+v2+json” https://yourapp/api/example
با استفاده از سربرگ سفارشی (X-API-Version):
curl -L -H “X-API-Version: 2” https://yourapp/api/example
مسیری که به صراحت نسخه شده است (با api.version:v2 در تعریف مسیر):
curl -L https://yourapp/api/example
هیچ هدری برای مسیرهایی که به طور صریح نسخه شده نیاز نیست، زیرا نسخه در خود مسیر تنظیم شده است.
مزایای نسخه Laravel API
ادغام آسان: راه اندازی سریع در پروژه های جدید یا موجود لاراول.
نسخه قابل انعطاف: بین تشخیص مبتنی بر هدر و کنترل نسخه صریح انتخاب کنید.
وضوح کنترل کننده دینامیک: درخواست ها به طور خودکار به کنترلرهای نسخه شده هدایت می شوند.
سازگاری به عقب: از نسخه های قدیمی API بدون تغییر مسیرها یا کنترلرها پشتیبانی کنید.
قابل تنظیم: سرصفحه ها، نسخه های پیش فرض و فضاهای نام را متناسب با پروژه خود تنظیم کنید.
نتیجه گیری
نسخه API لاراول یک راه حل قدرتمند و سبک برای مدیریت نسخه های API در لاراول است. چه در حال ساخت یک API جدید باشید یا یک API موجود، این بسته کد شما را ماژولار، تمیز و قابل نگهداری نگه می دارد.
با پشتیبانی از تشخیص مبتنی بر هدر با الهام از نسخه‌سازی API GitHub و انعطاف‌پذیری برای تعیین مستقیم نسخه‌ها، نسخه API Laravel یک رویکرد ساده برای مدیریت نسخه‌های متعدد ارائه می‌کند.
برای ساده سازی نسخه API در برنامه Laravel خود آماده هستید؟ با نسخه API Laravel در GitHub شروع کنید و همین امروز نسخه قابل مدیریت و مقیاس پذیر را به API خود بیاورید!
عکس توسط Codioful (به Gradienta سابق) در Unsplash
در چشم انداز توسعه امروزی، API ها ستون فقرات بسیاری از برنامه ها هستند و امکان ادغام در سیستم های مختلف را فراهم می کنند.
همانطور که الزامات و ویژگی‌ها تکامل می‌یابند، نسخه‌سازی API برای حفظ سازگاری به عقب ضروری می‌شود و تضمین می‌کند که مشتریان موجود همانطور که انتظار می‌رود به کار خود ادامه می‌دهند در حالی که نسخه‌های جدید عملکردهای پیشرفته‌تری را معرفی می‌کنند.
پس زمینه: از دینگو API تا نسخه Laravel API
از لحاظ تاریخی، من به بسته محبوب دینگو API برای پروژه‌های مبتنی بر لاراول، به ویژه برای مدیریت نسخه‌سازی API، متکی بوده‌ام.
دینگو API مدتهاست که یک راه حل قابل اعتماد برای مدیریت نسخه ها و ارائه سایر ابزارهای خاص API در لاراول بوده است.
با این حال، با تکامل لاراول و اکوسیستم آن، نیاز به یک راه حل ساده تر و هدفمندتر نیز افزایش یافت. نسخه API لاراول فقط این را ارائه می دهد: یک بسته متمرکز و آسان برای پیاده سازی برای مدیریت نسخه، بدون سربار اضافی از ویژگی هایی که ممکن است به آن نیاز نداشته باشید.
علاوه بر این، نسخه API لاراول بسته از رویکرد GitHub به نسخه API الهام گرفته است. نسخه REST API GitHub از ترکیبی از هدرهای سفارشی و Accept هدرها برای مشخص کردن نسخه‌ها، که رویکردی تمیز و انعطاف‌پذیر را ارائه می‌دهد که URLها را ثابت نگه می‌دارد و در عین حال امکان کنترل نسخه را فراهم می‌کند.
با نسخه Laravel API، می‌توانید از یک استراتژی مشابه مبتنی بر هدر استفاده کنید یا کنترل نسخه صریح را در مسیرهای خود انتخاب کنید.
آشنایی با استراتژی های نسخه سازی API
انتخاب استراتژی نسخه سازی مناسب برای API شما بسیار مهم است. در اینجا نگاهی به رایج ترین استراتژی ها، همراه با مزایا و معایب آنها می اندازیم:
| استراتژی | توضیحات | جوانب مثبت | منفی |
|---|---|---|---|
| نسخه URI | نسخه API در مسیر URL مشخص شده است، به عنوان مثال، https://api.example.com/v1/resource
|
– اجرای ساده و آسان – پاک کردن نسخه در URL |
– صلبیت URL (تغییر نسخه بر ساختار URL تأثیر می گذارد) – آرامش کمتری دارد زیرا URL ها معمولاً فقط برای منابع هستند |
| نسخه پرس و جو پارامتر | نسخه به عنوان پارامتر پرس و جو اضافه می شود، به عنوان مثال، https://api.example.com/resource?version=1
|
– URL قابل انعطاف – URL پایه ثابت می ماند |
– URL را با پارامترها به هم می زند – در API های REST کمتر رایج است |
| نسخه‌سازی مبتنی بر سربرگ | نسخه به صورت سرصفحه ارسال می شود، به عنوان مثال، Accept: application/vnd.example+v1+json یا X-API-Version: 1، با الهام از رویکرد GitHub |
– URL های تمیز (بدون نسخه در URL) – کنترل نسخه قابل انعطاف |
– مشتریان باید هدرها را به درستی تنظیم کنند، که می تواند پیچیدگی را اضافه کند – نسخه در URL قابل مشاهده نیست |
| کنترل نسخه صریح | نسخه مستقیماً در کد مشخص شده است، بنابراین کلاینت ها نسخه را کنترل نمی کنند که برای API های داخلی ایده آل است | – کنترل کامل بر نسخه سازی – به پیکربندی مشتری متکی نیست |
– محدود کننده، برای API های عمومی مناسب نیست – نیاز به نگهداری مسیر برای هر نسخه |
هر استراتژی دارای نقاط قوت و مبادلات منحصر به فردی است، بنابراین ضروری است که یکی را انتخاب کنید که با نیازها و الگوهای استفاده API شما هماهنگ باشد.
چرا نسخه API لاراول را انتخاب کنید؟
نسخه API لاراول طراحی شده است تا نسخه API در برنامه های لاراول را آسان و انعطاف پذیر کند. این بر روی یک رویکرد ساده برای مسیریابی درخواست‌ها به کنترل‌کننده نسخه صحیح با استفاده از یکی از موارد زیر تمرکز دارد:
- تشخیص نسخه مبتنی بر سربرگ: ایده آل برای API های عمومی که در آن مشتریان می توانند نسخه را از طریق هدرها مشخص کنند.
- کنترل صریح نسخه: نسخه ها را مستقیماً در مسیرها یا گروه های مسیر مشخص کنید، مناسب برای API های داخلی یا کاملاً کنترل شده.
با نسخه Laravel API، می توانید:
- شناسایی و مسیریابی درخواست ها بر اساس
Acceptهدرها یا هدرهای سفارشی - صراحتاً نسخه‌ها را در هر مسیر یا گروه مسیر مشخص کنید، با عبور از تشخیص هدر.
- فضاهای نام قابل تنظیم را برای کنترلرهای نسخه شده تعریف کنید.
- چندین نسخه API را بدون مسیرها یا کنترلرهای به هم ریخته مدیریت کنید.
شروع به کار با نسخه API لاراول
در اینجا یک راهنمای سریع برای نصب و پیکربندی Laravel API Version آورده شده است.
مرحله 1: بسته را نصب کنید
بسته را از طریق Composer نصب کنید:
composer require cleaniquecoders/laravel-api-version
مرحله 2: فایل پیکربندی را منتشر کنید
برای سفارشی کردن بسته، فایل پیکربندی آن را با دستور زیر منتشر کنید:
php artisan vendor:publish --tag="laravel-api-version-config"
این یک ایجاد خواهد کرد config/api-version.php فایل در این فایل می‌توانید نسخه پیش‌فرض را تنظیم کنید، هدرها را سفارشی کنید، فضای نام ریشه را پیکربندی کنید و موارد دیگر.
پیکربندی نمونه
در اینجا نگاهی اجمالی به فایل پیکربندی پیش فرض داریم:
return [
'default_version' => 'v1',
'use_accept_header' => true,
'custom_header' => 'X-API-Version',
'accept_header_pattern' => '/application\/vnd\.\w+\+v(\d+(\.\d+)*)\+json/',
'root_namespace' => 'App\Http\Controllers\Api',
];
تنظیمات کلیدی عبارتند از:
-
default_version: اگر نسخه ای مشخص نشده باشد، نسخه پیش فرض API استفاده می شود. -
use_accept_header: برای شناسایی نسخه ها ازAcceptهدر -
custom_header: یک هدر سفارشی برای نسخه‌سازی تنظیم کنید (پیش‌فرض استX-API-Version). -
root_namespace: فضای نام پایه را برای کنترلرهای نسخه شده تعریف کنید.
مرحله 3: تعریف مسیرهای نسخه شده
Laravel API نسخه ارائه می دهد api.version میان افزاری که از قبل هنگام نصب این بسته پیکربندی شده است و به شما امکان می دهد مسیرهای نسخه شده را به راحتی تعریف کنید.
گزینه 1: تشخیص نسخه مبتنی بر سربرگ
برای فعال کردن تشخیص خودکار نسخه از هدرها، از api.version میان افزار در مسیرهای شما میان‌افزار نسخه‌ها را از هر کدام شناسایی می‌کند Accept یا X-API-Version هدرها و به صورت پویا درخواست ها را به فضای نام نسخه شده صحیح هدایت می کند.
در routes/api.php:
use Illuminate\Support\Facades\Route;
Route::middleware(['api', 'api.version'])->group(function () {
Route::get('/example', 'ExampleController@index');
// Add other routes for this version
});
با این تنظیمات، درخواست ها می توانند نسخه را از طریق سرصفحه هایی مانند:
-
Acceptهدر:Accept: application/vnd.yourapp+v2+json -
هدر سفارشی:
X-API-Version: 2
گزینه 2: تنظیم صریح نسخه
اگر ترجیح می دهید نسخه را مستقیماً در مسیرها مشخص کنید، با عبور از تشخیص هدر، نسخه را به عنوان پارامتر به میان افزار ارسال کنید:
Route::middleware(['api', 'api.version:v2'])->group(function () {
Route::get('/example', 'ExampleController@index');
// Additional routes for version 2
});
با تعریف api.version:v2، تمام مسیرهای این گروه بدون توجه به هدرها به فضای نام نسخه 2 هدایت می شوند.
نمونه درخواست ها
در اینجا نحوه فراخوانی API نسخه شده خود با استفاده از نسخه Laravel API آورده شده است.
-
با استفاده از
Acceptسربرگ:
curl -L -H "Accept: application/vnd.yourapp+v2+json" https://yourapp/api/example
-
با استفاده از سربرگ سفارشی (
X-API-Version):
curl -L -H "X-API-Version: 2" https://yourapp/api/example
-
مسیری که به صراحت نسخه شده است (با
api.version:v2در تعریف مسیر):
curl -L https://yourapp/api/example
هیچ هدری برای مسیرهایی که به طور صریح نسخه شده نیاز نیست، زیرا نسخه در خود مسیر تنظیم شده است.
مزایای نسخه Laravel API
- ادغام آسان: راه اندازی سریع در پروژه های جدید یا موجود لاراول.
- نسخه قابل انعطاف: بین تشخیص مبتنی بر هدر و کنترل نسخه صریح انتخاب کنید.
- وضوح کنترل کننده دینامیک: درخواست ها به طور خودکار به کنترلرهای نسخه شده هدایت می شوند.
- سازگاری به عقب: از نسخه های قدیمی API بدون تغییر مسیرها یا کنترلرها پشتیبانی کنید.
- قابل تنظیم: سرصفحه ها، نسخه های پیش فرض و فضاهای نام را متناسب با پروژه خود تنظیم کنید.
نتیجه گیری
نسخه API لاراول یک راه حل قدرتمند و سبک برای مدیریت نسخه های API در لاراول است. چه در حال ساخت یک API جدید باشید یا یک API موجود، این بسته کد شما را ماژولار، تمیز و قابل نگهداری نگه می دارد.
با پشتیبانی از تشخیص مبتنی بر هدر با الهام از نسخه‌سازی API GitHub و انعطاف‌پذیری برای تعیین مستقیم نسخه‌ها، نسخه API Laravel یک رویکرد ساده برای مدیریت نسخه‌های متعدد ارائه می‌کند.
برای ساده سازی نسخه API در برنامه Laravel خود آماده هستید؟ با نسخه API Laravel در GitHub شروع کنید و همین امروز نسخه قابل مدیریت و مقیاس پذیر را به API خود بیاورید!
عکس توسط Codioful (به Gradienta سابق) در Unsplash
