RESTful API là gì?

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:

GET    /api/users           → Lấy danh sách user
GET    /api/users/123       → Lấy thông tin user id=123
POST   /api/users           → Tạo user mới
PUT    /api/users/123       → Cập nhật toàn bộ user id=123
PATCH  /api/users/123       → Cập nhật một phần user id=123
DELETE /api/users/123       → Xóa user id=123

(c) Không nhúng hành động vào URL

❌ Sai:

POST /api/createUser
GET  /api/getUserById/123

✅ Đú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:

/api/v1/users
/api/v2/users

(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

GET    /api/posts           → Lấy danh sách bài viết
GET    /api/posts/10        → Lấy chi tiết bài viết id=10
POST   /api/posts           → Tạo bài viết mới
PUT    /api/posts/10        → Cập nhật toàn bộ bài viết id=10
PATCH  /api/posts/10        → Cập nhật một phần bài viết id=10
DELETE /api/posts/10        → Xóa bài viết id=10

⮕ 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.