
RESTful API là một kiến trúc thiết kế API cho phép các hệ thống giao tiếp qua HTTP. Trong bài viết này, bạn sẽ tìm hiểu về nguyên tắc RESTful, cách sử dụng HTTP methods đúng mục đích, tài nguyên định danh bằng URL, cách trả về JSON, và các status code chuẩn.
1. RESTful API là gì?
-
REST = Representational State Transfer: một kiến trúc thiết kế API cho phép các hệ thống giao tiếp với nhau qua giao thức HTTP.
-
RESTful API = API được xây dựng tuân theo các nguyên tắc REST.
-
Ý tưởng: tài nguyên (resource) được định danh bằng URL, và ta thao tác trên tài nguyên bằng các HTTP methods (GET, POST, PUT, DELETE, PATCH…).
2. Chuẩn RESTful API
Một API được gọi là RESTful khi tuân thủ các nguyên tắc sau:
(a) Sử dụng HTTP Methods đúng mục đích
-
GET
→ Lấy dữ liệu (read) -
POST
→ Tạo mới (create) -
PUT
→ Cập nhật toàn bộ (update) -
PATCH
→ Cập nhật một phần (partial update) -
DELETE
→ Xoá dữ liệu
(b) Resource phải được định danh bằng URL
Ví dụ quản lý users:
(c) Không nhúng hành động vào URL
❌ Sai:
✅ Đúng:
POST /api/users GET /api/users/123
(d) Sử dụng JSON (hoặc XML, nhưng JSON phổ biến nhất)
Dữ liệu trả về nên ở dạng JSON, dễ đọc và parse.
Ví dụ response:
{ "id": 123, "name": "Thanh Nguyen", "email": "[email protected]" }
(e) Stateless (không lưu trạng thái ở server)
-
Server không lưu trạng thái session của client.
-
Mỗi request phải tự chứa đầy đủ thông tin (vd: token xác thực trong header).
(f) Sử dụng HTTP Status Code chuẩn
-
200 OK
→ Thành công -
201 Created
→ Tạo mới thành công -
400 Bad Request
→ Request sai dữ liệu -
401 Unauthorized
→ Chưa xác thực -
403 Forbidden
→ Không có quyền -
404 Not Found
→ Không tìm thấy tài nguyên -
500 Internal Server Error
→ Lỗi server
(g) Versioning (phiên bản API)
Để tránh phá vỡ khi nâng cấp, nên version API:
(h) HATEOAS (tuỳ chọn nâng cao)
RESTful chuẩn có thể kèm link hướng dẫn hành động tiếp theo.
Ví dụ:
{ "id": 123, "name": "Thanh", "links": { "self": "/api/v1/users/123", "posts": "/api/v1/users/123/posts" } }
3. Ví dụ chuẩn RESTful API cho hệ thống Blog
⮕ Tóm gọn: RESTful API = API dùng HTTP method đúng mục đích + tài nguyên định danh bằng URL + stateless + JSON + status code chuẩn.