API Development với Laravel

Khi một hệ thống cần phục vụ cả website, ứng dụng di động và đối tác bên ngoài, API là cách để các bên trao đổi dữ liệu với nhau. Laravel có sẵn nhiều công cụ giúp việc xây dựng RESTful API nhanh và có tổ chức.

RESTful API là gì?

REST tổ chức API xoay quanh tài nguyên (sản phẩm, đơn hàng, người dùng). Mỗi tài nguyên có một đường dẫn, và phương thức HTTP cho biết hành động:

• GET /api/products: lấy danh sách sản phẩm
• GET /api/products/1: lấy một sản phẩm
• POST /api/products: tạo mới
• PUT hoặc PATCH /api/products/1: cập nhật
• DELETE /api/products/1: xóa

Dữ liệu thường được trao đổi ở định dạng JSON.

Các thành phần trong Laravel

Routes

Route của API khai báo trong routes/api.php và tự có tiền tố /api. Từ Laravel 11, file này được tạo bằng lệnh php artisan install:api. Một dòng Route::apiResource('products', ProductController::class) sinh đủ các route cho thao tác thêm, xem, sửa, xóa.

Controllers

Controller nhận request, gọi phần xử lý nghiệp vụ và trả về JSON. Lệnh php artisan make:controller ProductController --api tạo sẵn các phương thức cần thiết.

Kiểm tra dữ liệu đầu vào

Dùng Form Request để tách quy tắc kiểm tra ra khỏi controller. Khi dữ liệu không hợp lệ, Laravel tự trả về mã 422 kèm danh sách lỗi theo từng trường.

API Resources

Resource quyết định dữ liệu nào được trả về và ở dạng nào. Nhờ lớp chuyển đổi này, bạn có thể đổi cấu trúc bảng mà không làm thay đổi cấu trúc JSON các ứng dụng đang dùng.

Xác thực

• Sanctum: gọn nhẹ, cấp token cho ứng dụng di động và hỗ trợ xác thực cho giao diện SPA. Phù hợp với phần lớn dự án.
• Passport: triển khai đầy đủ OAuth2, dùng khi cần cấp quyền cho ứng dụng của bên thứ ba.

Dùng đúng mã trạng thái HTTP

• 200: thành công; 201: đã tạo mới; 204: thành công, không có nội dung trả về
• 401: chưa xác thực; 403: không có quyền
• 404: không tìm thấy tài nguyên
• 422: dữ liệu gửi lên không hợp lệ
• 429: gọi quá nhiều lần trong thời gian ngắn
• 500: lỗi phía máy chủ

Những điều nên làm

1. Phân trang cho mọi endpoint trả về danh sách, ví dụ bằng paginate().
2. Đánh phiên bản API (/api/v1/...) để thay đổi sau này không làm hỏng ứng dụng cũ.
3. Giới hạn tần suất gọi bằng middleware throttle.
4. Thống nhất định dạng lỗi trên toàn bộ API.
5. Viết tài liệu theo chuẩn OpenAPI (Swagger) để bên sử dụng tự tra cứu.
6. Viết test cho các endpoint quan trọng.

Kết luận

Laravel lo phần hạ tầng như định tuyến, kiểm tra dữ liệu, xác thực, để bạn tập trung thiết kế API rõ ràng và nhất quán. Một API được thiết kế tốt ngay từ đầu sẽ tiết kiệm rất nhiều công sức khi hệ thống có thêm ứng dụng di động hay đối tác tích hợp.