Thay đổi API mà không làm bên sử dụng bị bất ngờ

Thêm trường trông có vẻ vô hại cho đến khi ứng dụng kiểm tra nghiêm ngặt từ chối nó. Giữ tên trường có vẻ an toàn cho đến khi ý nghĩa thay đổi. Tương thích là thỏa thuận về hành vi giữa bên cung cấp và bên sử dụng. Nhãn phiên bản giúp tổ chức thỏa thuận, nhưng không chứng minh bản phát hành giữ nguyên nó.

Xem cả ý nghĩa lẫn cấu trúc

OpenAPI cung cấp mô tả chuẩn về API HTTP mà con người và công cụ đều có thể hiểu.[1] Dùng so sánh đặc tả để tìm đầu vào, đầu ra và thao tác thay đổi. Coi so sánh đó là điểm bắt đầu duyệt, không phải toàn bộ đánh giá tương thích.

Duyệt giá trị mặc định, đơn vị, thứ tự, phân quyền và cách báo lỗi cùng schema. Trường phản hồi mới có thể phù hợp với ứng dụng bỏ qua trường lạ, nhưng không phải ứng dụng nào cũng vậy. Trường bắt buộc mới trong yêu cầu có thể khiến ứng dụng cũ không gửi được yêu cầu hợp lệ. Kiểm thử đúng những bên sử dụng đang hỗ trợ, thay vì mặc định họ chấp nhận thay đổi.

Lập bản đồ tác động đến bên sử dụng

Nên lập danh sách ứng dụng đang hoạt động, kèm người phụ trách, phiên bản hợp đồng hỗ trợ và quy trình quan trọng. Với mỗi thay đổi đề xuất, nêu rõ giả định nào có thể hỏng. Hỏi xem ứng dụng có sinh mã từ schema, kiểm tra phản hồi nghiêm ngặt hay rẽ nhánh theo tập giá trị liệt kê không.

Chọn một trong ba hướng: tương thích trong hợp đồng đã thống nhất, hành vi phải đăng ký dùng, hoặc chuyển đổi rõ ràng. Soạn hướng dẫn chuyển đổi trước khi công bố hạn chót. Nếu hành vi cũ và mới cùng tồn tại, nêu cách yêu cầu chọn hành vi và dữ liệu nào vẫn dùng chung. Duy trì nhiều phiên bản làm tăng công bảo trì, nên đừng tạo phiên bản mới cho mọi khác biệt hình thức.

Đặt yêu cầu bằng chứng trước phát hành

Chọn bộ dữ liệu mẫu và kiểm thử hành vi đại diện cho phía sử dụng. Có cả kết quả rỗng, giá trị chưa biết và tình huống lỗi. Duyệt phương án quay về trước khi phát hành, nhất là khi chuyển đổi dữ liệu không thể đảo ngược đơn giản. Theo dõi lỗi thực tế thay vì coi triển khai thành công là tích hợp thành công.

• Xác định bên sử dụng bị ảnh hưởng bởi thay đổi ý nghĩa và schema.
• Kiểm thử yêu cầu từ ứng dụng cũ với hành vi dịch vụ dự kiến.
• Cung cấp ví dụ, các bước chuyển đổi và đầu mối xử lý vấn đề.
• Chốt bằng chứng tiếp nhận và giới hạn quay lui trước khi bỏ hành vi cũ.

Ví dụ giả định: thêm trạng thái giao hàng

Ví dụ giả định: API lô hàng thêm trạng thái kiểm tra. Một ứng dụng hiển thị giá trị chưa biết là đang chờ, còn ứng dụng khác từ chối giá trị ngoài tập liệt kê được sinh trong mã. Nhờ dữ liệu kiểm thử chung, bên cung cấp phát hiện khác biệt trước khi phát hành.

Các nhóm chọn hợp đồng phải đăng ký dùng cho trạng thái mới và ghi rõ cách ánh xạ tạm cho ứng dụng cũ. Ánh xạ làm mất chi tiết, nên bộ phận vận hành vẫn cần trạng thái đầy đủ trong màn hình riêng. Bước tiếp theo là liệt kê bên sử dụng trường bị ảnh hưởng và yêu cầu từng chủ ứng dụng kiểm thử giá trị mới thật sự, không chỉ duyệt ghi chú phát hành.