Versiones

La versión va en la ruta: todas las rutas viven bajo /api/v1/.

Lo que promete v1

Dentro de v1 las cosas solo se agregan:

• Campos nuevos en una fila o en un sobre.
• Valores nuevos de una enumeración: un state nuevo, una etiqueta nueva en labels, un source nuevo de un día esperado.
• Parámetros de consulta nuevos, siempre opcionales.
• Rutas nuevas.
• Códigos de error nuevos, para situaciones que antes no podían pasar.

Nada se quita, se renombra ni cambia de significado. Un campo que existe conserva su nombre, su tipo y lo que cuenta.

Escriba su cliente para que lo que se agrega nunca lo rompa: ignore los campos que no conoce y trate un valor desconocido de una enumeración como "otra cosa" y no como un error.

Qué es una v2

Un cambio que rompería un cliente, como quitar un campo, renombrarlo o cambiar lo que significa un número, va a una versión nueva bajo /api/v2/. Cuando eso pase, v1 sigue respondiendo a la par por un tiempo anunciado en los cambios, para que haya tiempo de mudarse.

Lo que no es un cambio del API

Los números de un reporte cambian cuando cambian los datos de la empresa: una marca aprobada, un horario corregido, un feriado nuevo. Eso es el reporte haciendo su trabajo, no el API cambiando. Las reglas que los calculan son las de la app, las mismas para la página de reportes, su Excel y este API.

El detail de un error es un mensaje para una persona y puede cambiar de redacción en cualquier momento; su code, no.