REST API Design Best Practices — txt1.ai

Do Marcus Chen, Kiến Trúc Sư API Chính với 14 năm xây dựng hệ thống mở rộng tại các công ty fintech và chăm sóc sức khỏe

Ba năm trước, tôi đã chứng kiến một startup tiêu tốn 2,3 triệu USD trong chi phí kỹ thuật vì thiết kế API của họ thực sự bị lỗi. Họ đã xây dựng một hệ thống xử lý thanh toán với 47 điểm cuối khác nhau, các quy tắc đặt tên không nhất quán và không có chiến lược phiên bản. Khi họ cần thêm một tính năng mới cho khách hàng lớn nhất của mình, các thay đổi đã lan truyền qua toàn bộ hệ thống của họ như một chuỗi domino. Sáu tháng sau khi tái cấu trúc, họ đã mất khách hàng lớn nhất và cắt giảm 40% đội ngũ kỹ thuật của mình.

Thảm họa đó đã dạy tôi một điều quan trọng: Thiết kế API không chỉ đơn thuần là làm cho mọi thứ hoạt động hôm nay. Nó liên quan đến việc xây dựng một hợp đồng giữa hệ thống của bạn và thế giới có thể phát triển một cách thanh thoát trong nhiều năm, xử lý hàng triệu yêu cầu và vẫn đủ trực quan để các nhà phát triển thực sự muốn sử dụng nó. Sau khi dành hơn một thập kỷ thiết kế các API xử lý hàng tỷ giao dịch hàng năm, tôi đã nhận ra rằng sự khác biệt giữa một API tốt và một API tuyệt vời thường chỉ phụ thuộc vào một vài nguyên tắc cơ bản mà hầu hết các đội ngũ đều bỏ qua.

Nền Móng: Hiểu Biết Về REST Ngoài Các Từ Khóa

Khi tôi bắt đầu sự nghiệp của mình vào năm 2010, REST đã là phong cách kiến trúc chiếm ưu thế cho các API web, nhưng tôi nhận thấy rằng nhiều nhà phát triển coi nó như một danh sách kiểm tra hơn là một triết lý. REST là viết tắt của Chuyển Giao Trạng Thái Đại Diện, và nó được xây dựng dựa trên sáu ràng buộc cốt lõi mà Roy Fielding đã phác thảo trong luận án tiến sĩ của mình. Nhưng điều quan trọng trong thực hành là: REST là về việc xem tài nguyên API của bạn như các danh từ, sử dụng các phương thức HTTP như động từ, và duy trì tính vô trạng thái.

Nguyên tắc vô trạng thái đã giúp tôi tiết kiệm vô số giờ gỡ lỗi. Mỗi yêu cầu từ khách hàng đến máy chủ phải chứa tất cả thông tin cần thiết để hiểu và xử lý yêu cầu đó. Không có trạng thái phiên trên máy chủ. Điều này có nghĩa là API của bạn có thể mở rộng theo chiều ngang mà không cần quản lý phiên phức tạp, và bất kỳ máy chủ nào trong cụm của bạn cũng có thể xử lý bất kỳ yêu cầu nào. Khi tôi thiết kế API thanh toán cho một nền tảng chăm sóc sức khỏe xử lý 3,2 triệu giao dịch hàng ngày, nguyên tắc này cho phép chúng tôi mở rộng từ 4 máy chủ lên 47 trong các thời điểm cao mà không cần thay đổi một dòng mã ứng dụng nào.

Nhưng REST không phải là giáo điều. Tôi đã thấy nhiều đội lãng phí hàng tuần tranh cãi về việc liệu điều gì đó có "thực sự là RESTful" hay không khi họ nên tập trung vào tính nhất quán và khả năng sử dụng. Mục tiêu là tạo ra một API mà các nhà phát triển có thể hiểu một cách trực quan. Nếu bạn đang sử dụng các phương thức HTTP một cách chính xác, tổ chức tài nguyên một cách logic và duy trì tính vô trạng thái, bạn đã đạt được 90% mục tiêu. 10% còn lại là về các mẫu thực tiễn làm cho API của bạn trở thành niềm vui để sử dụng thay vì là nguồn thất vọng.

Đặt Tên Tài Nguyên: Nghệ Thuật Về Các URL Trực Quan

Cấu trúc URL của bạn là điều đầu tiên mà các nhà phát triển thấy, và nó thiết lập kỳ vọng cho toàn bộ API của bạn. Tôi tuân theo một quy tắc đơn giản: sử dụng danh từ cho các tài nguyên, giữ chúng ở dạng số nhiều, và tổ chức chúng theo dạng phân cấp khi có mối quan hệ cha-con rõ ràng. Ví dụ, /api/v1/users/12345/orders/67890 ngay lập tức cho bạn biết rằng bạn đang xem đơn hàng 67890 thuộc về người dùng 12345.

"API tốt nhất là một API mà các nhà phát triển có thể dự đoán điểm cuối tiếp theo trước khi đọc tài liệu của bạn—đó là khi bạn biết rằng bạn đã đạt được sự nhất quán thực sự."

Đây là nơi mà hầu hết các đội sai lầm: họ trộn động từ vào các URL của họ. Tôi đã xem xét các API với các điểm cuối như /api/getUser hoặc /api/createOrder. Điều này là dư thừa vì các phương thức HTTP đã cung cấp động từ. GET /api/users/12345 là rõ ràng hơn và RESTful hơn so với GET /api/getUser/12345. Phương thức HTTP cho bạn biết bạn đang thực hiện hành động gì; URL cho bạn biết bạn đang hành động trên tài nguyên nào.

Tính nhất quán quan trọng hơn sự hoàn hảo. Trong một dự án, chúng tôi đã tranh luận về việc có nên sử dụng /users hay /accounts cho tài nguyên người dùng của chúng tôi. Chúng tôi đã dành ba giờ đồng hồ trong cuộc họp đó. Điều quan trọng không phải là thuật ngữ nào chúng tôi chọn, mà là chúng tôi đã chọn một và giữ vững nó trong toàn bộ API. Chúng tôi đã ghi lại quyết định của mình, thêm nó vào hướng dẫn kiểu API và tiếp tục. Sự nhất quán đó có nghĩa là các nhà phát triển có thể dự đoán được tên điểm cuối mà không cần phải kiểm tra tài liệu liên tục.

Đối với các tài nguyên lồng nhau, tôi giới hạn độ sâu tối đa là hai đến ba cấp. Hơn thế nữa, các URL trở nên cồng kềnh và mối quan hệ trở nên không rõ ràng. Nếu bạn thấy mình đang viết /api/companies/123/departments/456/teams/789/members/012, bạn đã đi quá xa. Thay vào đó, hãy xem xét việc biến các đội thành tài nguyên cấp cao nhất với các tham số truy vấn: /api/teams/789/members?company=123&department=456. Điều này giữ cho các URL có thể quản lý trong khi vẫn cho phép bạn lọc và xác định tầm nhìn cho các tài nguyên một cách hợp lý.

Các Phương Thức HTTP: Sử Dụng Công Cụ Đúng Cho Công Việc

HTTP cung cấp cho chúng ta một từ vựng phong phú về các phương thức, nhưng tôi thấy các nhà phát triển thường xuyên sử dụng sai hoặc giới hạn bản thân chỉ trong GET và POST. Hiểu được ý nghĩa ngữ nghĩa của mỗi phương thức đã giúp tôi xây dựng các API vừa trực quan vừa có thể lưu cache. GET lấy tài nguyên và phải là idempotent và an toàn—gọi nó nhiều lần sẽ tạo ra cùng một kết quả mà không có tác dụng phụ. POST tạo ra tài nguyên mới. PUT thay thế một tài nguyên hoàn chỉnh. PATCH cập nhật một phần của tài nguyên. DELETE loại bỏ một tài nguyên.

Tính idempotency của PUT so với POST là rất quan trọng cho độ tin cậy. Khi tôi xây dựng một API quản lý tồn kho cho một chuỗi bán lẻ với 847 cửa hàng, chúng tôi đã sử dụng PUT cho các cập nhật đặc biệt bởi vì đảm bảo tính idempotency của nó. Nếu một sự cố mạng khiến yêu cầu được gửi hai lần, PUT đảm bảo rằng chúng tôi sẽ không vô tình tạo ra các bản ghi trùng lặp hoặc áp dụng cùng một cập nhật nhiều lần. Quyết định đơn giản này đã ngăn chặn ước tính khoảng 12.000 sự không khớp tồn kho trong năm hoạt động đầu tiên.

PATCH chưa được sử dụng nhiều nhưng có giá trị vô cùng. Thay vì yêu cầu các khách hàng gửi toàn bộ đại diện tài nguyên cho các cập nhật nhỏ, PATCH cho phép các cập nhật từng phần. Khi cập nhật một hồ sơ người dùng với 30 trường, tại sao phải bắt các khách hàng gửi cả 30 trường khi họ chỉ muốn thay đổi địa chỉ email? PATCH /api/users/12345 với thân là {"email": "[email protected]"} sẽ hiệu quả hơn và ít sai sót hơn so với việc yêu cầu toàn bộ tài nguyên.

DELETE cũng nên là idempotent. Gọi DELETE trên một tài nguyên đã bị xóa nên trả về 204 No Content hoặc 404 Not Found, không phải lỗi. Điều này làm cho logic thử lại trở nên đơn giản hơn và đáng tin cậy hơn. Tôi đã thực hiện các xóa mềm, nơi DELETE đánh dấu một tài nguyên là không hoạt động thay vì loại bỏ nó về mặt vật lý, điều này cung cấp một dấu vết kiểm toán và cho phép phục hồi. Điều quan trọng là các cuộc gọi DELETE tiếp theo đến cùng một tài nguyên tạo ra cùng một kết quả—tài nguyên đã biến mất trong quan điểm của khách hàng.

Mã Trạng Thái: Nói Trôi Chảy Ngôn Ngữ Của HTTP