REST API Best Practices: A Practical Checklist for 2026 — cod-ai.com

Ba năm trước, tôi đã chứng kiến một startup tiêu tốn 2,3 triệu đô la trong vòng vốn vì API của họ không thể mở rộng qua 10.000 người dùng. Vấn đề không phải là cơ sở hạ tầng hay thiết kế cơ sở dữ liệu của họ - mà là kiến trúc REST API của họ. Là một người đã dành 14 năm qua để xây dựng và duy trì APIs cho các công ty từ các startup nho nhỏ cho đến các doanh nghiệp Fortune 500, tôi đã thấy mô hình này lặp đi lặp lại nhiều lần hơn tôi muốn đếm. Tôi là Marcus Chen, Kiến trúc sư API chính tại một công ty fintech lớn, và tôi đã thiết kế các REST API hiện đang xử lý hơn 47 tỷ yêu cầu mỗi tháng. Hôm nay, tôi đang chia sẻ danh sách kiểm tra thực tiễn có thể đã cứu được startup đó - và có thể sẽ cứu được startup của bạn.

Cảnh quan phát triển API đã thay đổi mạnh mẽ kể từ khi tôi bắt đầu trong lĩnh vực này. Về cơ bản, vào năm 2011, nếu API của bạn có thể trả về JSON và xử lý các thao tác cơ bản CRUD, bạn đã đi trước thời đại. Vào năm 2026, tiêu chuẩn cao hơn gấp bội. API của bạn cần phải an toàn, hiệu suất tốt, có thể quan sát được, và thân thiện với nhà phát triển - tất cả trong khi xử lý các trường hợp ngoại lệ chưa từng tồn tại năm năm trước. Đây không phải là lời khuyên lý thuyết từ một ai đó đã đọc vài bài viết trên blog. Đây là những kiến thức đã được thử nghiệm từ một người đã gỡ lỗi các sự cố sản xuất vào lúc 3 giờ sáng, tối ưu hóa các điểm cuối đã tốn hàng nghìn đô la mỗi ngày trong hóa đơn đám mây, và đào tạo hàng chục kỹ sư về các nguyên tắc thiết kế API thực sự có tác dụng trong thế giới thực.

Đặt Tên Tài Nguyên và Thiết Kế URI: Nền Tảng Mà Mọi Người Đều Sai

Để bắt đầu, tôi sẽ nói về một điều dường như cơ bản nhưng thường làm khó ngay cả các nhà phát triển dày dạn kinh nghiệm: đặt tên tài nguyên. Trong quý vừa qua, tôi đã xem xét các API từ 23 đội nhóm khác nhau trong tổ chức của chúng tôi. Mười chín trong số đó có các quy ước đặt tên không nhất quán khiến API của họ khó sử dụng và duy trì. Điều này không chỉ là về thẩm mỹ - việc đặt tên kém ảnh hưởng trực tiếp đến trải nghiệm của nhà phát triển, điều này dẫn đến thời gian tích hợp lâu hơn và nhiều phiếu hỗ trợ hơn.

Dưới đây là nguyên tắc cơ bản: các URI của bạn nên biểu thị tài nguyên, không phải hành động. Sử dụng danh từ, không phải động từ. Tôi thường thấy sai lầm này: các điểm cuối như /getUser hoặc /createOrder. Đây là các điểm cuối theo kiểu RPC giả làm REST. Cách tiếp cận chính xác sử dụng các phương thức HTTP để chỉ ra hành động: GET /users/123 hoặc POST /orders. Điều này có thể có vẻ hình thức, nhưng nó rất quan trọng. Khi tôi tái cấu trúc API xử lý thanh toán của chúng tôi để tuân theo mô hình này một cách nhất quán, thời gian tích hợp với các đối tác mới giảm từ trung bình 8.3 ngày xuống còn 4.1 ngày.

Sử dụng danh từ số nhiều cho các tập hợp. Luôn luôn. Tôi không quan tâm nếu điều đó có cảm giác ngữ pháp không phù hợp - tính nhất quán vượt trội hơn ngữ pháp. Điểm cuối của bạn nên là /users, không phải /user. Khi bạn kết hợp các hình thức số ít và số nhiều, bạn buộc các nhà phát triển phải ghi nhớ những quyết định tùy ý. Tôi đã thấy các đội lãng phí hàng giờ trong các cuộc họp tranh luận xem một điểm cuối nên số ít hay số nhiều. Hãy tiết kiệm cho bản thân sự đau đầu đó: số nhiều cho tập hợp, luôn luôn.

Các mối quan hệ phân cấp nên được phản ánh trong cấu trúc URI của bạn, nhưng đừng đi sâu hơn ba cấp độ. Ví dụ, /users/123/orders/456/items/789 trở nên cồng kềnh. Vào thời điểm đó, hãy cân nhắc việc khiến các items trở thành một tài nguyên cấp cao với việc lọc: /items?orderId=456. Tôi đã học bài học này theo cách khó khăn khi chúng tôi xây dựng một API thương mại điện tử có năm cấp sâu. Mã trở nên không thể duy trì, và chúng tôi đã phải mất hai tháng để tái cấu trúc nó.

Sử dụng dấu gạch ngang, không phải dấu gạch dưới, trong các URI. Đây là một chi tiết nhỏ nhưng cải thiện khả năng đọc: /order-items dễ đọc hơn /order_items. Quan trọng hơn, một số hệ thống xử lý dấu gạch dưới khác nhau, và dấu gạch ngang thì an toàn trên toàn cầu. Giữ mọi thứ trong chữ thường. Việc sử dụng chữ hoa trong các URI có thể gây rắc rối vì một số hệ thống phân biệt chữ hoa và chữ thường trong khi một số khác thì không.

Phiên bản API của bạn từ ngay ngày đầu. Tôi không thể nhấn mạnh điều này đủ. Sử dụng phiên bản URI như /v1/users hoặc /v2/orders. Tôi đã thử nghiệm phiên bản dựa trên header, phiên bản tham số truy vấn, và thương lượng nội dung. Phiên bản URI là cách trực tiếp nhất và gây ra ít đau đầu nhất. Khi chúng tôi ra mắt API mà không có phiên bản, chúng tôi đã tự dồn mình vào một góc chỉ trong vòng sáu tháng. Những thay đổi phá vỡ trở nên không thể triển khai mà không gây ra hỗn loạn cho các tích hợp hiện có.

Phương Thức HTTP và Mã Trạng Thái: Nói Đúng Ngôn Ngữ

Nếu việc đặt tên tài nguyên là nền tảng, thì phương thức HTTP và mã trạng thái là ngữ pháp của các API REST. Sử dụng chúng một cách chính xác không phải là tùy chọn - đó là cách bạn giao tiếp ý định và kết quả với người tiêu dùng API. Tôi đã xem xét hàng trăm API mà các nhà phát triển đối xử với các phương thức HTTP như những gợi ý thay vì các thông số kỹ thuật. Điều này tạo ra sự nhầm lẫn, làm hỏng bộ nhớ đệm và khiến API của bạn trở nên không đoán trước được.

"Việc đặt tên tài nguyên trong API của bạn không chỉ là về thẩm mỹ - đó là sự khác biệt giữa các nhà phát triển tích hợp trong vài ngày so với vài tuần, và điều đó ảnh hưởng trực tiếp đến lợi nhuận của bạn."

Các yêu cầu GET phải an toàn và idempotent. An toàn có nghĩa là chúng không thay đổi trạng thái máy chủ. Idempotent có nghĩa là gọi chúng nhiều lần sẽ tạo ra cùng một kết quả. Tôi đã từng tiếp nhận một API mà các yêu cầu GET đang tạo ra bản ghi trong cơ sở dữ liệu. Hỗn loạn mà điều này gây ra thật tuyệt vời - việc trình duyệt tiền xử lý và các trình thu thập liên kết đã tạo ra hàng nghìn bản ghi sai. Chúng tôi đã phải mất ba tuần để dọn dẹp mớ hỗn độn này và sửa thiết kế.

POST được sử dụng để tạo ra tài nguyên. Khi bạn POST tới /orders, bạn đang tạo ra một đơn hàng mới. Phản hồi nên trả về 201 Created với một tiêu đề Location trỏ tới tài nguyên mới: Location: /orders/789. Bao gồm tài nguyên được tạo trong phần thân phản hồi. Điều này giúp khách hàng không phải thực hiện thêm một yêu cầu GET. Trong hệ thống xử lý đơn hàng của chúng tôi, tối ưu hóa đơn giản này đã giảm số lượng cuộc gọi API xuống 31% và cải thiện hiệu suất được cảm nhận một cách đáng kể.

PUT được sử dụng cho các bản cập nhật đầy đủ và nên được idempotent. Nếu bạn PUT cùng một dữ liệu tới /users/123 mười lần, kết quả nên giống hệt như khi thực hiện một lần. PATCH được sử dụng cho các bản cập nhật từng phần. Sử dụng PATCH khi các khách hàng chỉ cần gửi các trường đã thay đổi. Điều này giảm kích thước tải trọng và làm cho việc cập nhật hiệu quả hơn. Trong API hồ sơ người dùng của chúng tôi, việc chuyển từ PUT sang PATCH cho các cập nhật hồ sơ đã giảm kích thước tải trọng trung bình từ 4.2KB xuống còn 0.8KB.

DELETE nên trả về 204 No Content cho các xóa thành công. Một số nhà phát triển trả lại 200 OK với một thông điệp xác nhận, nhưng 204 thì chính xác hơn về mặt ngữ nghĩa - không có nội dung để trả lại vì tài nguyên đã biến mất. Hãy làm cho DELETE cũng phải idempotent. Việc xóa một tài nguyên đã được xóa trước đó nên trả về 204, không phải 404. Điều này ngăn ngừa tình trạng cạnh tranh trong các hệ thống phân tán.

Mã trạng thái quan trọng hơn bạn nghĩ. Sử dụng 200 OK cho các yêu cầu GET, PUT, và PATCH thành công. Sử dụng 201 Created cho các yêu cầu POST thành công. Sử dụng 204 No Content cho các yêu cầu DELETE thành công.