Thêm vào một tập hợp các tùy chọn hữu hạn; thay đổi phá vỡ API?

9

Lấy điểm cuối API HTTP tạo ra mô hình phản hồi sau:

{
    "type": "Dog",
    "name": "Jessi",
    ...
}

Các typelĩnh vực đã được mô tả trong tài liệu như là một trong những Dog, Cathoặc Fish.

Việc thêm một tùy chọn mới Ratcó thể được coi là thay đổi API không?

Việc thêm một tùy chọn vào danh sách hữu hạn (mà nhà phát triển có thể bật) đã xem xét một phần mở rộng hoặc sửa đổi cho API?

— Dave mới
nguồn

10

Nếu tài liệu mô tả trường này là một trong Dog, Cat hoặc Fish, thì có, việc thêm một loại khác sẽ thay đổi giao diện theo cách không tương thích ngược. Hoàn toàn có thể hiểu được rằng một người tiêu dùng API của bạn đã viết mã cụ thể để đối phó với chó và mèo khác với cá. Đưa ra một loại không xác định, người tiêu dùng đó sẽ không biết phải làm gì với phản hồi của bạn. Nhưng điều này phụ thuộc rất nhiều vào những gì mà các trình giữ chỗ này loại Cat Cat và và Fish Fish thể hiện trong miền vấn đề thực tế của bạn

Nếu thay đổi danh sách các loại có thể xảy ra thường xuyên hoặc nếu danh sách không hữu hạn, thì việc ghi lại tài liệu này là hợp lý. Tùy thuộc vào các trường hợp sử dụng của bạn, có thể tốt để hiển thị danh sách tất cả các loại có thể là điểm cuối trong API của bạn - theo cách đó rõ ràng bạn có thể thêm hoặc xóa các loại mà không phải cập nhật phiên bản API. Tuy nhiên, các loại của bạn càng năng động, người tiêu dùng API càng khó thực hiện một loại cụ thể nào đó. Việc mở rộng hay dễ sử dụng là quan trọng hơn tùy thuộc vào trường hợp sử dụng và miền vấn đề của bạn.

— amon
nguồn

Câu trả lời tuyệt vời - cảm ơn. Điều gì xảy ra nếu tài liệu chi tiết các tùy chọn trong một số bảng có tiêu đề "bảng sau mô tả các động vật hiện được API hỗ trợ ." Điều này không chỉ ra rằng các tùy chọn có thể được mở rộng theo?

— Dave New

1

@davenewza Đó có lẽ là một ý tưởng tốt nhưng tôi sẽ rõ ràng hơn. Đừng chỉ nói những gì bạn muốn nói - hãy nói trực tiếp! Tôi sẽ cố gắng đặt kỳ vọng rõ ràng và đưa ra một đảm bảo về tính ổn định trong các tài liệu cho điểm cuối đó, đại loại như: Bảng Bảng sau liệt kê các động vật hiện được hỗ trợ, mặc dù chúng tôi có thể thêm hoặc xóa động vật được hỗ trợ trong tương lai. Khi điều đó xảy ra, chúng tôi sẽ cập nhật số phiên bản nhỏ của API.

— amon

Đặc điểm kỹ thuật thực thi >>> đặc tả tài liệu >>> đặc điểm kỹ thuật không có giấy tờ.

— VoiceOfUnreason

0

Nó sẽ chỉ bị phá vỡ nếu "Chuột" có thể được trả lại từ các hoạt động hiện có.

Nếu các hoạt động hiện tại không thể trả về "Rat" thì việc thêm tùy chọn mới này sẽ không có hiệu lực.

— Jon Raynor
nguồn