Menambah serangkaian opsi yang terbatas; perubahan API yang melanggar?

9

Ambil titik akhir HTTP API yang mengeluarkan model respons berikut:

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

The typelapangan telah dijelaskan dalam dokumentasi sebagai salah satu Dog, Catatau Fish.

Apakah menambahkan opsi baru, katakanlah Rat, dianggap sebagai perubahan API yang melanggar?

Apakah menambahkan opsi ke daftar terbatas (yang dapat diaktifkan pengembang) dianggap sebagai ekstensi atau modifikasi API?

rest api api-design json Dave New
sumber

Jawaban:

10

Jika dokumentasi menggambarkan bidang ini sebagai salah satu dari Anjing, Kucing, atau Ikan, maka ya, menambahkan jenis lain akan mengubah antarmuka dengan cara yang tidak kompatibel ke belakang. Dapat dibayangkan sepenuhnya bahwa konsumen API Anda telah menulis kode khusus untuk menangani anjing dan kucing secara berbeda dari pada ikan. Dengan tipe yang tidak dikenal, konsumen itu tidak akan tahu apa yang harus dilakukan dengan respons Anda. Tapi ini sangat tergantung pada apa yang diwakili oleh jenis placeholder ini "Kucing" dan "Ikan" dalam domain masalah Anda yang sebenarnya ...

Jika perubahan pada daftar tipe yang mungkin sering terjadi, atau jika daftar tidak terbatas, maka mendokumentasikan hal ini adalah masuk akal. Bergantung pada kasus penggunaan Anda, mungkin baik untuk mengekspos daftar semua jenis yang mungkin sebagai titik akhir di API Anda - dengan cara itu jelas Anda dapat menambah atau menghapus jenis tanpa harus memperbarui versi API. Namun, semakin dinamis jenis Anda, semakin sulit bagi konsumen API untuk melakukan sesuatu yang spesifik jenis. Apakah ekstensibilitas atau kemudahan penggunaan lebih penting tergantung pada kasus penggunaan dan domain masalah Anda.

amon
sumber
Jawaban yang fantastis - terima kasih. Bagaimana jika dokumentasi merinci opsi dalam beberapa tabel berjudul "tabel berikut ini menjelaskan tentang hewan yang saat ini didukung oleh API." Apakah ini tidak menunjukkan bahwa opsi dapat diperluas?
Dave New
1
@davenewza Itu mungkin ide yang bagus tapi saya akan lebih eksplisit. Jangan hanya menunjukkan apa yang Anda maksud - katakan langsung! Saya akan mencoba menetapkan ekspektasi yang jelas dan menawarkan jaminan stabilitas dalam dokumen untuk titik akhir itu, seperti: “Tabel berikut mencantumkan hewan yang saat ini didukung, meskipun kami dapat menambah atau menghapus hewan yang didukung di masa depan. Ketika itu terjadi, kami akan memperbarui nomor versi minor dari API. "
amon
Spesifikasi yang dapat dieksekusi >>> spesifikasi terdokumentasi >>> spesifikasi tidak berdokumen.
VoiceOfUnreason
0

Itu hanya akan melanggar jika "Tikus" dapat dikembalikan dari operasi yang ada.

Jika operasi yang ada tidak dapat mengembalikan "Rat" maka menambahkan opsi baru ini tidak akan berpengaruh.

Jon Raynor
sumber