ایجاد API های خوب یک مهارت اساسی برای هر توسعه دهنده موفق بک اند است. آنها ستون های اصلی زیر برنامه های تلفن همراه یا برنامه های تک صفحه ای مورد علاقه شما هستند.
لاراول (Laravel) محبوب ترین فریمورک PHP، ابزارهای زیادی را در اختیار شما قرار می دهد تا به شما کمک کند موارد مورد نیاز خود را به روشی استاندارد بسازید. برای این مقاله، فرض می‌کنم که شما حداقل یک مورد را قبلاً ساخته‌اید، زیرا هدف من پوشش کامل موضوع نیست. اما اگر با API نویسی در لاراول آشنا نیستید این مقاله را مطالعه کنید.
بهترین روش های API های Laravel RESTful
قبل از هر چیزی برای API های خود حتما داکیومنت بنویسید، می توانید از سواگر یا Postman برای این مورد استفاده کنید، زیرا هم خودتان هم توسعه دهندگان دیگر به راحتی می توانند با API نوشته شده ارتباط برقرار کنند و سرعت توسعه دادن بیشتر از قبل شود.
برای آشنایی با طراحی API خوب و تمیز می توانید این مقاله را بررسی کنید.
از متد های صحیح HTTP استفاده کنید
متد های HTTP به نوعی مانند زبانی هستند که وب سرور شما به آن صحبت می کند. وقتی در حال ساختن یک API هستید، باید آن را نیز بیان کنید.
استفاده از متد های HTTP مناسب واقعاً مهم است زیرا به API شما اجازه می‌دهد تا ارتباط مؤثرتری برقرار کند و برای توسعه‌دهندگانی که از آن استفاده می‌کنند، شهودی‌تر خواهد بود.
به عنوان مثال، فرض کنید یک کتاب دیجیتالی در یک کتابخانه داریم. اگر بخواهیم آن را بخوانیم، از متد GET استفاده می کنیم. اگر بخواهیم کتاب جدیدی به کتابخانه اضافه کنیم، از متد POST استفاده می کنیم. برای به روز رسانی اطلاعات یک کتاب موجود، از متد PUT یا PATCH استفاده می کنیم. و در نهایت وقتی می خواهیم کتاب را از کتابخانه حذف کنیم از متد DELETE استفاده می کنیم.
حال، لاراول چگونه در این مورد کمک می کند؟ این مسیرهایی را برای استفاده آسان فراهم می کند که با این متد های HTTP مطابقت دارند:
Route::get('/posts', [PostController::class, 'index']);
Route::get('/posts/{post}', [PostController::class, 'show']);
Route::post('/posts', [PostController::class, 'store']);
Route::put('/posts/{post}', [PostController::class, 'update']);
Route::delete('/posts/{post}', [PostController::class, 'destroy']);از مسیرهای منابع API استفاده کنید
لاراول یک راه آسان و راحت برای ایجاد مسیرهای API با استفاده از متد apiResource ارائه می دهد. این به توسعه دهندگان کمک می کند تا به سرعت مسیرهایی را برای API های خود تنظیم کنند.
هم اکنون به چگونگی کارکرد آن می پردازیم:
در لاراول، apiResource متدی است که به طور خودکار مسیرهای اصلی را که برای یک API نیاز داریم را شامل می شود. مسیرهایی را برای index, store, show, update, و destroy متد ها ایجاد می‌کند، به استثنای متد های create و edit، زیرا این دو معمولاً برای بازگرداندن view استفاده می‌شوند که در API به آنها نیازی نداریم.
مثلا:
use App\Http\Controllers\PhotoController;
Route::apiResource('photos', PhotoController::class);در کد بالا، photos URL است و PhotoController کلاسی است که درخواست‌های این URL را مدیریت می‌کند.
اگر می خواهید مسیرهایی را برای بسیاری از کنترلرها به طور همزمان ایجاد کنید، به سادگی از متد apiResources استفاده کنید و یک آرایه با جفت های 'url' => 'Controller' مانند این ارسال کنید:
use App\Http\Controllers\PhotoController;
use App\Http\Controllers\PostController;
Route::apiResources([
'photos' => PhotoController::class,
'posts' => PostController::class,
]);این به طور خودکار photos و posts ی URL را به ترتیب توسط PhotoController و PostController تنظیم می‌کند.
در نهایت، هنگام ایجاد یک Controller جدید برای API خود، لاراول یک دستور مفید php artisan make:controller ControllerName --api را ارائه می دهد. افزودن گزینه api-- به لاراول اطلاع می دهد که این کنترلر برای یک API است و متد های create و edit را در کد boilerplate حذف می کند.
لاراول واقعاً راه اندازی API ها را آسان می کند!
از منابع API Eloquent استفاده کنید
منابع API راهی برای تبدیل مدل های داده به ساختارهای JSON قابل استفاده است. آنها یک لایه تبدیل بین مدل های شما و پاسخ های API برنامه شما ایجاد می کنند.
آنها را به عنوان یک واسطه در نظر بگیرید. آنها داده‌ها را از مدل‌های شما می‌گیرند، آنها را به هم می‌ریزند یا فیلتر می‌کنند و سپس آنها را به عنوان پاسخ JSON تحویل می‌دهند.
هنگامی که یک کلاس resource تولید می کنید، می توانید نحوه نگاشت ویژگی ها از یک مدل به نمایش JSON را تعریف کنید. شما به سادگی از متد toArray برای برگرداندن آرایه ای استفاده می کنید که با ساختار مورد نظر شما در پاسخ JSON مطابقت دارد. و می توانید مستقیماً از شی منبع خود به خصوصیات مدل دسترسی پیدا کنید.
در اینجا یک مثال است:
public function toArray(Request $request): array
{
return [
'id' => $this->id,
'name' => $this->name,
'email' => $this->email,
];
}ایجاد منابع با استفاده از دستور make:resource Artisan انجام می شود. به عنوان مثال، اگر می‌خواهید یک UserResource ایجاد کنید، اجرا می‌کنید:
php artisan make:resource UserResource
همچنین می‌توانید مجموعه‌های منابع را با استفاده از make:resource با فلگ collection-- یا با افزودن collection به نام منبع ایجاد کنید.
در اینجا یک نمونه از collection (مجموعه) UserResource آورده شده است:
php artisan make:resource User --collection
یا:
php artisan make:resource UserCollection
در لاراول، هنگام ایجاد پاسخ از مسیر یا کنترلر، از این منابع استفاده می کنید.
برای یک منبع، شما فقط یک نمونه جدید از منبع را که با مدلی که می خواهید تبدیل کنید، برگردانید:
Route::get('/user/{id}', function (string $id) {
return new UserResource(User::findOrFail($id));
});برای collection ها، از متد collection در کلاس منبع استفاده خواهید کرد:
Route::get('/users', function () {
return UserResource::collection(User::all());
});اگر می خواهید در مورد عملکردهای پیشرفته و سایر سناریوهای استفاده بیاموزید، به شما توصیه می کنم که اسناد کامل لاراول را در مورد منابع API مرور کنید.
از پاسخ های JSON استفاده کنید
هنگامی که یک منبع Eloquent را در کنترلر خود برمی گردانید، لاراول به طور خودکار یک پاسخ JSON را تنظیم می کند.
در صورتی که اینطور نیست، متد json برای تنظیم خودکار هدر Content-Type روی application/json و تبدیل آرایه داده شده به JSON مفید است:
return response()->json([
'foo' => 'bar',
]);از کد HTTP صحیح برای پاسخ ها استفاده کنید
بازگرداندن کد HTTP مناسب در پاسخ شما بسیار مهم است.
در حرفه خود، احتمالاً به APIهای وحشتناکی که کد وضعیت 200 را با { "message": "Error!" } یا چیزی شبیه به آن است را برخورد کرده اید. لطفا، از آن دسته توسعه دهنده نباشید!
ما می خواهیم API های ما تا حد امکان آموزنده باشد. در اینجا یک نقطه شروع خوب است که تقریباً برای هر موردی مناسب است:
فهرست و دریافت منابع: 200 (OK).
ایجاد منابع: 201 (Created).
به روز رسانی منابع: 200 (OK).
حذف منابع: 204 (Not Content).
نیاز به احراز هویت برای دسترسی به منابع: 401 (Forbidden).
دسترسی غیرمجاز به منابع: 403 (Unauthorized).
منابع گمشده: 404 (Not Found).
مشکلی پیش آمد: 500 (Internal Server Error).
لاراول یک هلپر مفید به نام ()response می دهد که به ما امکان می دهد کد HTTP را که باید در پاسخ خود وارد کنیم را مشخص کنیم:
return response(
['foo' => 'bar'],
201
);یک پاسخ خالی با کد وضعیت 204 برگردانید:
response()->noContent();
یک منبع نیاز به احراز هویت دارد، unauthorized است، 404 است یا 500 است:
abort(401);
abort(403);
abort(404);
abort(500);در زمان احراز هویت با استفاده از Laravel Sanctum یا Passport صرفه جویی کنید
توضیح تفاوت های ظریف بین این دو پکیج همیشه دشوار است. اما اجازه دهید مورد بررسی قرار دهیم:
پاسپورت لاراول را می توان در مواقعی که به احراز هویت مانند فیس بوک، گوگل، ایکس (توئیتر سابق) و غیره برای احراز هویت کاربران خود نیاز دارید، استفاده کرد.
از سوی دیگر، Laravel Sanctum مانند یک سیستم احراز هویت کمتر سخت‌گیرانه است که برای پروژه‌های ساده مانند برنامه‌های تک صفحه‌ای یا تلفن همراه بهترین عملکرد را دارد.
اساساً، اگر هنوز مطمئن نیستید، به جای گیر افتادن، ابتدا از Laravel Sanctum استفاده کنید و اگر برنامه شما به چیز پیشرفته تری نیاز داشت، آن را به پاسپورت ارتقا دهید. وقتی زمانش رسید متوجه خواهید شد!
مطمئن شوید که مسیرهای نقاط پایانی شما تغییر نمی کند.
در اینجا یک نکته برای افرادی که با تست آشنا هستند وجود دارد: از هلپر ()route در تست های خود استفاده نکنید.
بیایید یک تست بسازیم:
test('the endpoint works as expected', function () {
$this
->get(route('foo'))
->assertOk();
});حال اگر مسیر را از foo/ به bar/ تغییر دهیم چه می شود؟ تست همچنان قبول می شود که بد است. به همین دلیل بسیاری از کدهای کاربران شکسته می شوند.
بنابراین بله، در عوض، این کار را انجام دهید:
test('the endpoint works as expected', function () {
$this
->get('/foo')
->assertOk();
});اکنون، اگر به دلایلی مسیر شما به مسیر دیگری تغییر کند، تست شکسته می‌شود و نمی‌توانید در production مستقر شوید.
جهت آشنایی با امنیت در API در لاراول این مقاله را بررسی کنید.
نتیجه
در پایان، ساختن یک API RESTful با توسعه لاراول مستلزم پیروی از بهترین شیوه ها و استفاده از ابزارهای مناسب است. با اتخاذ این شیوه ها، توسعه دهندگان می توانند یک API قوی و کارآمد را تضمین کنند. استخدام توسعه دهندگان ماهر با تجربه در لاراول نیز می تواند روند توسعه را تا حد زیادی بهبود بخشد. استخدام توسعه دهندگان از راه دور نیز ارزش توجه دارد، زیرا آنها انعطاف پذیری و دسترسی به یک استخر استعداد گسترده تر را ارائه می دهند. با وجود تیم و ابزار مناسب، ساختن یک API موفق RESTful با لاراول قابل دستیابی و پاداش است.
