Agregar a un conjunto finito de opciones; un cambio de ruptura de API?

9

Tome un punto final de la API HTTP que escupe el siguiente modelo de respuesta:

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

El typecampo se ha descrito en la documentación como uno de Dog, Cato Fish.

¿Agregar una nueva opción, por ejemplo Rat, se consideraría un cambio de API de última hora?

¿Agregar una opción a una lista finita (que un desarrollador puede activar) considera una extensión o una modificación de una API?

rest api api-design json Dave New
fuente

Respuestas:

10

Si la documentación describe este campo como uno de Perro, Gato o Pez, entonces sí, agregar otro tipo cambia la interfaz de una manera incompatible con versiones anteriores. Es totalmente concebible que un consumidor de su API haya escrito un código específico para tratar con perros y gatos de manera diferente que con los peces. Dado un tipo desconocido, ese consumidor no sabría qué hacer con su respuesta. Pero esto depende mucho de lo que estos tipos de marcador de posición "Gato" y "Pez" representan en su dominio del problema real ...

Si los cambios en la lista de tipos posibles son frecuentes, o si la lista no es finita, entonces documentar esto como tal es sensato. Dependiendo de sus casos de uso, podría ser bueno exponer una lista de todos los tipos posibles como punto final en su API; de esa manera está claro que puede agregar o eliminar tipos sin tener que actualizar la versión de la API. Sin embargo, cuanto más dinámicos sean sus tipos, más difícil será para los consumidores de API hacer algo específico para cada tipo. Si la extensibilidad o la facilidad de uso es más importante depende de sus casos de uso y su dominio del problema.

amon
fuente
Fantástica respuesta: gracias. ¿Qué sucede si la documentación detalla las opciones en alguna tabla titulada con "la siguiente tabla describe los animales que actualmente admite la API"? ¿Esto no indica que las opciones podrían ampliarse?
Dave New
1
@davenewza Probablemente sea una buena idea, pero sería más explícito. No solo indique lo que quiere decir, ¡dígalo directamente! Intentaría establecer expectativas claras y ofrecer una garantía de estabilidad en los documentos para ese punto final, algo así como: “La siguiente tabla enumera los animales actualmente admitidos, aunque podemos agregar o eliminar animales compatibles en el futuro. Cuando eso suceda, actualizaremos el número de versión menor de la API ".
amon
Especificación ejecutable >>> especificación documentada >>> especificación no documentada.
VoiceOfUnreason
0

Solo se rompería si "Rata" pudiera ser devuelta de las operaciones existentes.

Si las operaciones existentes no pueden devolver "Rata", agregar esta nueva opción no tendría ningún efecto.

Jon Raynor
fuente