Thống nhất hợp đồng API trước khi phát triển song song

Hai nhóm có thể hoàn tất công việc nhưng vẫn hiểu khác nhau về API. Một nhóm coi ngày giao hàng bị thiếu là chưa biết. Nhóm kia coi đó là giao ngay. Hợp đồng cần giải quyết khác biệt này trước khi phát triển song song tạo ra hành vi không tương thích.

Chốt quyết định, không chỉ tên trường

OpenAPI mô tả khả năng của API HTTP bằng một dạng mô tả giao diện chuẩn mà con người và công cụ đều có thể hiểu.[1] Hãy dùng nó để mô tả đường dẫn, tham số, nội dung yêu cầu, phản hồi và yêu cầu bảo mật. Bổ sung ví dụ giải thích ý nghĩa nghiệp vụ của các trường quan trọng.

Yêu cầu người phụ trách sản phẩm làm rõ giá trị thiếu, đơn vị, múi giờ và chuyển trạng thái. Phân biệt yêu cầu được nhận để xử lý với thao tác nghiệp vụ đã hoàn tất. Phản hồi truyền tải thành công không được biến thành lời hứa ngầm rằng mọi hoạt động phía sau đều xong.

Biến thỏa thuận thành thứ có thể kiểm tra

Nên lưu đặc tả chung trong hệ thống quản lý phiên bản, với người chịu trách nhiệm cho từng thao tác. Duyệt yêu cầu mẫu cùng phản hồi dự kiến. Cung cấp bản mô phỏng cho nhóm gọi API, nhưng nêu rõ những hành vi mà bản mô phỏng không tái hiện.

Dùng kiểm tra schema và kiểm thử phía sử dụng như hai công cụ khác nhau. Schema kiểm tra cấu trúc mà nhóm đã khai báo. Kiểm thử phía sử dụng kiểm tra một giả định về hành vi. Không công cụ nào thay thế việc trao đổi về phân quyền, thứ tự hay xử lý khi dịch vụ phụ thuộc gặp lỗi. Vẫn phải dành thời gian tích hợp với dịch vụ thật.

Giữ hợp đồng đầu tiên đủ gọn để có thể duyệt kỹ. Với tình huống biên chưa giải quyết, cần có quy tắc tạm thời rõ ràng, người chịu trách nhiệm quyết định và kiểm thử giúp cả hai nhóm nhìn thấy giới hạn đó.

Duyệt danh sách sẵn sàng thực tế

Trước khi chia việc, yêu cầu mỗi bên trình bày một luồng thành công và hai luồng thất bại. Đừng duyệt hợp đồng chỉ vì công cụ đọc được đặc tả. Ghi câu hỏi còn mở thành quyết định có người phụ trách, thay vì để trong tin nhắn trao đổi.

• Chỉ định người phụ trách nghiệp vụ và người duyệt kỹ thuật cho từng thao tác.
• Phân biệt trường bắt buộc, không bắt buộc và được phép nhận null.
• Mô tả lỗi quyền truy cập, lỗi dữ liệu và cách báo hoàn tất bất đồng bộ.
• Thống nhất dữ liệu kiểm thử mẫu và quy trình duyệt thay đổi không tương thích.

Ví dụ giả định: lịch hẹn giao hàng

Ví dụ giả định: cổng kho gửi yêu cầu đặt lịch tới dịch vụ điều phối. Hai nhóm thống nhất rằng phản hồi chấp nhận chỉ trả mã theo dõi, không phải khung giờ bốc hàng đã xác nhận. Một thao tác tra cứu riêng báo trạng thái xác nhận hoặc từ chối.

Nhóm giao diện có thể xây màn hình chờ trong khi nhóm dịch vụ phát triển cơ chế phân bổ lịch. Cả hai cùng kiểm tra trường hợp hết chỗ và gửi lặp yêu cầu. Việc chuẩn bị tốn thời gian duyệt và có thể làm chậm lúc bắt đầu viết mã. Chi phí này hợp lý khi nhiều nhóm có nguy cơ phát triển theo cách hiểu khác nhau. Bước tiếp theo là buổi thống nhất hợp đồng ngắn, tập trung vào ý nghĩa nghiệp vụ chưa rõ, không phải buổi trình bày kiến trúc tổng quát.