Mở bài

Trong thời đại chuyển đổi số, các hệ thống phần mềm không còn hoạt động độc lập mà cần liên kết và giao tiếp với nhau qua API. Đặc biệt, các ứng dụng web, mobile, và hệ thống doanh nghiệp đều dựa vào RESTful API để trao đổi dữ liệu nhanh chóng, bảo mật và linh hoạt.

Với Laravel – framework PHP mạnh mẽ và phổ biến nhất hiện nay, việc xây dựng API RESTful không chỉ đơn giản mà còn cực kỳ tối ưu. Laravel cung cấp sẵn các công cụ mạnh mẽ như Eloquent ORM, Route Resource, API Resource, và Middleware, giúp lập trình viên dễ dàng xây dựng hệ thống API chuyên nghiệp chỉ trong vài bước.

Bài viết này sẽ hướng dẫn bạn từng bước xây dựng RESTful API hoàn chỉnh trong Laravel, từ thiết kế database, viết controller, định nghĩa route, cho đến cách bảo mật bằng Laravel Sanctum.
Đây là bài viết nằm trong chuỗi Khóa học lập trình PHP/Laravel thực chiến, giúp bạn làm chủ Laravel qua các ví dụ thực tế và ứng dụng doanh nghiệp.

RESTful API là gì?

Trước khi bắt tay vào code, hãy cùng ôn lại khái niệm cơ bản.

REST (Representational State Transfer) là một kiến trúc giúp các hệ thống giao tiếp với nhau qua HTTP. Một API RESTful tuân thủ các nguyên tắc sau:

1. Sử dụng các phương thức HTTP tiêu chuẩn:

   • GET → Lấy dữ liệu

   • POST → Thêm mới dữ liệu

   • PUT/PATCH → Cập nhật dữ liệu

   • DELETE → Xóa dữ liệu

2. Dữ liệu trả về ở định dạng JSON – phổ biến và dễ sử dụng với mọi nền tảng.

3. Stateless (phi trạng thái): Mỗi request độc lập, không lưu session.

4. Sử dụng URL rõ ràng, mô tả tài nguyên:
   Ví dụ:

   • /api/books → Danh sách sách

   • /api/books/5 → Chi tiết sách có id = 5

Nhờ tuân thủ nguyên tắc này, RESTful API trở thành nền tảng cho hầu hết các ứng dụng hiện đại như Facebook, Google, Zalo, hoặc Shopee.

Bước 1: Thiết kế Database cho API

Giả sử chúng ta xây dựng API quản lý thư viện gồm 2 bảng chính: books và categories.

Tạo migration

php artisan make:migration create_categories_table --create=categories
php artisan make:migration create_books_table --create=books

Trong file migration:

// categories
Schema::create('categories', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->timestamps();
});

// books
Schema::create('books', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->string('author');
    $table->decimal('price', 8, 2);
    $table->foreignId('category_id')->constrained('categories')->onDelete('cascade');
    $table->timestamps();
});

Chạy lệnh:

php artisan migrate

Bây giờ bạn đã có cơ sở dữ liệu sẵn sàng cho API.

Bước 2: Tạo Model và Controller

Tạo model Book và Category:

php artisan make:model Book -m
php artisan make:model Category -m

Tạo controller kiểu RESTful:

php artisan make:controller Api/BookController --api
php artisan make:controller Api/CategoryController --api

Bước 3: Định nghĩa Route cho API

Laravel hỗ trợ định nghĩa route API cực kỳ ngắn gọn bằng Route::apiResource.

Trong file routes/api.php:

use App\Http\Controllers\Api\BookController;
use App\Http\Controllers\Api\CategoryController;

Route::apiResource('categories', CategoryController::class);
Route::apiResource('books', BookController::class);

Các route tự động sinh ra:

Bước 4: Viết Controller cho RESTful API

Ví dụ: BookController

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\Book;
use Illuminate\Http\Request;

class BookController extends Controller
{
    public function index()
    {
        return response()->json(Book::with('category')->paginate(10));
    }

    public function store(Request $request)
    {
        $request->validate([
            'title' => 'required',
            'author' => 'required',
            'price' => 'required|numeric',
            'category_id' => 'required|exists:categories,id',
        ]);

        $book = Book::create($request->all());
        return response()->json($book, 201);
    }

    public function show($id)
    {
        $book = Book::with('category')->findOrFail($id);
        return response()->json($book);
    }

    public function update(Request $request, $id)
    {
        $book = Book::findOrFail($id);
        $book->update($request->all());
        return response()->json($book);
    }

    public function destroy($id)
    {
        Book::destroy($id);
        return response()->json(['message' => 'Book deleted successfully']);
    }
}

Giờ bạn đã có API CRUD hoàn chỉnh cho Book.

Bước 5: Test API bằng Postman

Bạn có thể kiểm tra API bằng công cụ Postman hoặc Insomnia:

• GET /api/books → Lấy danh sách sách

• POST /api/books → Gửi JSON:

  {
    "title": "Laravel for Beginners",
    "author": "John Doe",
    "price": 120.5,
    "category_id": 1
  }
  

• PUT /api/books/1 → Cập nhật sách

• DELETE /api/books/1 → Xóa sách

Tất cả kết quả trả về đều ở JSON format, chuẩn RESTful.

Bước 6: Chuẩn hóa dữ liệu với API Resource

Laravel hỗ trợ API Resource giúp bạn định dạng dữ liệu trả về một cách chuyên nghiệp.

Tạo resource:

php artisan make:resource BookResource

Trong file BookResource.php:

public function toArray($request)
{
    return [
        'id' => $this->id,
        'title' => $this->title,
        'author' => $this->author,
        'price' => number_format($this->price, 2),
        'category' => $this->category->name ?? null,
        'created_at' => $this->created_at->toDateTimeString(),
    ];
}

Trong BookController:

use App\Http\Resources\BookResource;

public function index()
{
    return BookResource::collection(Book::with('category')->paginate(10));
}

public function show($id)
{
    return new BookResource(Book::with('category')->findOrFail($id));
}

Kết quả trả về sẽ gọn gàng, dễ hiểu và nhất quán giữa các API.

Bước 7: Bảo mật API với Laravel Sanctum

Để bảo vệ API, ta có thể dùng Laravel Sanctum – giải pháp xác thực token nhẹ gọn.

Cài đặt:

composer require laravel/sanctum
php artisan migrate

Thêm middleware vào app/Http/Kernel.php:

'api' => [
    \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
    'throttle:api',
    \Illuminate\Routing\Middleware\SubstituteBindings::class,
],

Trong model User:

use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
}

Tạo route login:

Route::post('/login', [AuthController::class, 'login']);

Và trong AuthController:

public function login(Request $request)
{
    $credentials = $request->only('email', 'password');

    if (!Auth::attempt($credentials)) {
        return response()->json(['message' => 'Unauthorized'], 401);
    }

    $user = Auth::user();
    $token = $user->createToken('API Token')->plainTextToken;

    return response()->json(['token' => $token]);
}

Bây giờ mọi request đến API có thể kèm theo token trong header:

Authorization: Bearer <token>

Bước 8: Cấu trúc URL RESTful chuyên nghiệp

Một số gợi ý để bạn thiết kế API chuyên nghiệp hơn:

Bước 9: Tối ưu hiệu năng và phân trang

Laravel hỗ trợ sẵn paginate() giúp giảm tải cho API khi có hàng ngàn dữ liệu:

return BookResource::collection(Book::paginate(10));

Kết quả trả về:

{
  "data": [...],
  "links": {...},
  "meta": {...}
}

Giúp bạn dễ dàng tạo chức năng load more hoặc infinite scroll trên frontend.

Bước 10: Viết Unit Test cho API

Bạn có thể kiểm tra API tự động bằng PHPUnit:

php artisan make:test BookApiTest

public function test_book_index_returns_success()
{
    $response = $this->get('/api/books');
    $response->assertStatus(200);
}

Điều này giúp đảm bảo API luôn hoạt động đúng ngay cả khi cập nhật hệ thống.

Kết luận

Việc xây dựng RESTful API bằng Laravel không chỉ đơn giản mà còn cực kỳ mạnh mẽ. Chỉ trong vài bước, bạn đã có một hệ thống API hoàn chỉnh, có phân trang, có bảo mật, có định dạng dữ liệu chuyên nghiệp.

Từ những ví dụ trên, bạn có thể dễ dàng mở rộng ra các dự án thực tế như:

• API quản lý người dùng

• API bán hàng

• API học trực tuyến

• API siêu thị điện tử

Laravel thực sự là framework PHP mạnh nhất cho phát triển RESTful API, bởi sự linh hoạt, cú pháp ngắn gọn và hệ sinh thái đồ sộ.

🚀 Nếu bạn muốn làm chủ kỹ năng này, hãy tham gia Khóa học lập trình PHP/Laravel tại qviet.vn – nơi bạn được học qua các dự án thực tế, từ xây dựng website đến API chuyên nghiệp.

Hãy bắt đầu hôm nay – chỉ với vài dòng lệnh, bạn có thể tạo ra một hệ thống RESTful API đẳng cấp doanh nghiệp!