Gởi đến tất cả các backend developers đang xây dựng APIs cho đồng nghiệp frontend: nỗ lực của các bạn có thể tăng cường đáng kể năng suất của nhóm và thành công tổng thể. Đây là một hướng dẫn tinh chỉnh để giúp hợp tác của bạn mượt mà hơn, dựa trên kinh nghiệm của tôi như một developer full-stack. Đây không phải là về những nguyên tắc cơ bản của thực hành kỹ thuật tốt như readability (dễ đọc), consistency (tính nhất quán), hay stability (sự ổn định)—bạn đã nắm vững những điều đó. Thay vào đó, những kiến thức này nhằm làm cho việc làm việc với API của bạn trở nên dễ dàng hơn cho các frontend developers, cuối cùng là tăng tốc thời gian ra thị trường và đạt được những chỉ số ấn tượng mà các quản lý của bạn quan tâm.
Ưu tiên cấu trúc dữ liệu
Frontend developers bắt đầu bằng cách ánh xạ dữ liệu vào thiết kế. Chia sẻ mô hình dữ liệu của bạn sớm—trước khi API hoàn toàn sẵn sàng—có thể cực kỳ có lợi. Các frontend devs thường bắt đầu với các mô hình dữ liệu và có quyền truy cập vào các mô hình này trước sẽ tiết kiệm được nhiều phỏng đoán.
- TypeScript Interfaces: dịch các mô hình của bạn thành các interfaces TypeScript cung cấp một bước đầu tiên. ngay cả những người sử dụng JavaScript thuần túy cũng sẽ đánh giá cao việc biết tên các trường (field names) sớm. Tên có thể thay đổi, nhưng dễ dàng sửa chúng sau này hơn là phỏng đoán ban đầu.
- Tính nhất quán trong đặt tên: thỏa thuận về các quy ước đặt tên nhất quán là rất quan trọng. tránh các sự không đồng nhất như phương thức getUsers gọi endpoint GET /accounts. Các cuộc thảo luận sớm có thể giải quyết những vấn đề này.
- Mock Data: chia sẻ dữ liệu giả (mock data) cho phép các frontend devs kiểm tra các kịch bản khác nhau, bao gồm cả các trường hợp ngoại lệ và các trường tùy chọn. Nếu có thể, hãy truy cập vào Figma hoặc các công cụ thiết kế khác để căn chỉnh các mô hình dữ liệu với nhu cầu thiết kế thực tế.
Tối ưu hóa API Calls
Xem xét thiết kế để tối ưu hóa số lượng cuộc gọi API. Lý tưởng nhất là một cuộc gọi duy nhất có thể lấy tất cả dữ liệu hiển thị cho một trang.
- Hiệu quả trong một cuộc gọi: trong một thế giới hoàn hảo, một cuộc gọi API sẽ lấy tất cả dữ liệu cần thiết cho một trang. Mặc dù phân trang (pagination), cuộn vô hạn (infinite scroll), và các tối ưu hóa nhỏ khác là hợp lệ, việc lấy dữ liệu chính nên phản ánh thiết kế cuối cùng.
- Các cuộc gọi độc lập: Ensure that each API call can fail independently without breaking the entire UI. Each call should handle its own errors gracefully.
- Bulk Requests: đối với việc xử lý dữ liệu, cung cấp các endpoints hỗ trợ các thao tác hàng loạt (bulk operations) nếu thiết kế liên quan đến việc chỉnh sửa hàng loạt. điều này giảm số lượng yêu cầu và cải thiện hiệu quả.
Cung cấp dữ liệu mẫu thực tế
Khi tích hợp API, việc có dữ liệu mẫu đa dạng và thực tế là vô giá.
- Đa dạng trong dữ liệu: điền vào cơ sở dữ liệu phát triển của bạn với các ví dụ đa dạng để bao phủ các trường hợp sử dụng khác nhau. Điều này giúp các frontend developers phát hiện các vấn đề có thể không rõ ràng trong các bản mô phỏng thiết kế với dữ liệu lý tưởng hóa.
Chia sẻ chi tiết quan trọng
các yêu cầu phức tạp thường dẫn đến logic phức tạp trong API của bạn. Truyền đạt những sắc thái này có thể ngăn chặn sự hiểu lầm.
- Document Tricky Logic:nếu API của bạn có logic không thông thường, các phương thức bổ sung hoặc yêu cầu tham số cụ thể, hãy đảm bảo truyền đạt rõ ràng.
- Tránh giả định:điều gì có vẻ rõ ràng với bạn có thể không phải với người khác. Đừng giả định rằng các frontend developers sẽ hiểu được những phức tạp mà không có giải thích chi tiết.
Nhấn mạnh giao tiếp
Cuối cùng, chìa khóa cho sự hợp tác thành công là đối thoại mở. Mỗi nhóm làm việc khác nhau, vì vậy hãy tìm ra điều gì phù hợp nhất với nhóm của bạn.
- Align Processes: bắt đầu với danh sách này và điều chỉnh nó để phù hợp với quy trình làm việc của nhóm bạn. Dù đó là việc để các frontend devs phác thảo các endpoints trước hay liên quan đến một quản lý sản phẩm kỹ thuật, giao tiếp là cần thiết.
- API như một sản phẩm: hãy coi API của bạn như một sản phẩm dành cho các frontend developers. Hãy nỗ lực để tạo ra một API không chỉ chức năng mà còn thú vị khi sử dụng.
Tóm lại, hãy coi các frontend developers là người dùng chính của bạn và nỗ lực tạo ra một API đáp ứng nhu cầu của họ một cách liền mạch. Nỗ lực hợp tác của bạn sẽ dẫn đến một quy trình phát triển mạch lạc và hiệu quả hơn, cuối cùng là tạo ra một sản phẩm tốt hơn cho tất cả mọi người.
