RESTful API

REST API là cách để 2 chương trình (thường là client và server) giao tiếp với nhau qua HTTP: client gửi request tới 1 địa chỉ (URL) đại diện cho 1 dữ liệu/tài nguyên cụ thể, server trả về response cho biết kết quả. Thiết kế REST hiện nay là kết quả của một chuỗi giải pháp nối tiếp nhau: mỗi giải pháp giải quyết một vấn đề cụ thể của giải pháp trước, đồng thời để lộ ra một vấn đề mới, từ đó thúc đẩy giải pháp tiếp theo ra đời.

flowchart TD
    A["RPC / CORBA / DCOM<br/>gọi hàm ở máy khác qua giao thức riêng"] -->|"giao thức nhị phân,<br/>gắn chặt vào 1 ngôn ngữ/platform"| B["SOAP / XML-RPC<br/>chuẩn hoá bằng XML qua HTTP"]
    B -->|"XML nặng, đặc tả WS-* quá phức tạp,<br/>dùng HTTP như đường ống thuần tuý"| C["REST (Roy Fielding, 2000)<br/>tận dụng đúng HTTP: verb, status code, cache"]
    C -->|"tên gọi REST bị lạm dụng,<br/>không ai đo được API có RESTful thật không"| D["Richardson Maturity Model (2008)<br/>4 mức độ tuân thủ REST"]
    D -->|"nhiều team làm API riêng lẻ,<br/>frontend/mobile phải đợi backend xong mới làm được"| E["API Contract / OpenAPI<br/>đặc tả API trước, cả 2 phía dựa vào đó"]
    E -->|"REST vẫn có giới hạn: over-fetch,<br/>nhiều round-trip cho dữ liệu lồng nhau"| F["GraphQL / gRPC<br/>hướng đi khác cho từng bài toán cụ thể"]

#	Giải pháp	Vấn đề được giải quyết	Vấn đề mới phát sinh
1	RPC / CORBA / DCOM	Cho phép gọi hàm ở máy khác như gọi hàm local	Giao thức nhị phân riêng, gắn chặt vào 1 ngôn ngữ/platform, khó tương thích
2	SOAP / XML-RPC	Chuẩn hoá bằng XML, tương thích được nhiều ngôn ngữ/platform hơn	XML nặng, đặc tả WS-* (WS-Security, WSDL...) quá phức tạp, dùng HTTP chỉ như đường ống chứ không tận dụng cơ chế của nó (cache, status code)
3	REST (Roy Fielding, luận án tiến sĩ 2000)	Tận dụng chính HTTP làm giao thức ứng dụng: HTTP method là hành động, status code là kết quả, URL định danh resource, tận dụng cache sẵn có của web	Từ "REST"/"RESTful" bị dùng tràn lan cho bất kỳ API nào chạy trên HTTP, dù không tuân thủ đúng nguyên tắc — không có thước đo chung
4	Richardson Maturity Model (2008)	Đưa ra 4 mức để đánh giá một API "RESTful" đến đâu (xem bên dưới)	Biết đánh giá rồi nhưng nhiều team vẫn thiết kế lệch nhau, không có tài liệu chung cho backend/frontend/mobile cùng tham chiếu
5	API Contract / OpenAPI (Swagger)	Đặc tả API (endpoint, tham số, response) thành 1 tài liệu chuẩn, cả backend lẫn frontend/mobile cùng dựa vào để làm song song	REST thuần vẫn có giới hạn: client hay bị over-fetch/under-fetch dữ liệu, nhiều round-trip khi lấy dữ liệu lồng nhau
6	GraphQL / gRPC	Mỗi hướng giải quyết đúng 1 giới hạn của REST (GraphQL: client tự chọn field cần lấy; gRPC: hiệu năng cao cho giao tiếp nội bộ service-to-service)	— (lựa chọn theo bài toán, không thay thế hoàn toàn REST)

Richardson Maturity Model — 4 mức "RESTful thật sự"

Mức	Đặc điểm	Ví dụ
0	Chỉ có 1 endpoint, mọi hành động gửi qua POST, giống RPC-over-HTTP	POST /api với body mô tả hành động cần làm
1	Đã có nhiều resource riêng biệt (URI khác nhau cho từng loại dữ liệu) nhưng vẫn chỉ dùng 1-2 HTTP method	POST /getUser, POST /updateUser
2	Dùng đúng HTTP method (GET/POST/PUT/PATCH/DELETE) và đúng status code cho từng resource	GET /users/123, DELETE /users/123 — phần lớn API gọi là "RESTful" ngày nay dừng ở mức này
3	Thêm HATEOAS (Hypermedia as the Engine of Application State) — response trả kèm link tới các hành động/resource liên quan tiếp theo	Response trả về user kèm link "orders": "/users/123/orders" — hiếm khi triển khai đầy đủ trong thực tế

Lưu ý quan trọng: đạt mức 2 là đủ tốt cho phần lớn hệ thống thực tế. Mức 3 (HATEOAS) đúng chuẩn học thuật nhất nhưng ít được dùng vì tăng độ phức tạp mà lợi ích thực tế không tương xứng với hầu hết API nội bộ/mobile-facing.

Các trang tiếp theo đi vào chi tiết từng phần: thiết kế resource/URI, HTTP methods, status code, API Contract, và các quy ước phân trang/lọc/sắp xếp.