Versionado

Cómo funciona

La ruta lleva la versión mayor, como en /v1/api/properties. Una segunda versión mayor supondría un rediseño completo, correría junto a la v1 en lugar de sustituirla, y no es algo que pensemos hacer a la ligera.

La evolución del día a día ocurre a través de una revisión con fecha. Fíjala con una cabecera y tu integración conserva el comportamiento con el que se escribió:

Skautik-Version: 2026-08-01

Si omites la cabecera se aplica la revisión por defecto de tu organización, que es la vigente cuando se creó tu primera clave. No se mueve hacia delante en silencio, así que una integración no puede romperse porque nosotros hayamos publicado algo. Todas las respuestas devuelven la revisión que las sirvió.

Qué podemos cambiar sin una revisión nueva

Estos cambios son aditivos, y un cliente que siga una regla los tolera todos: ignora los campos que no reconozcas. Un parseador que rechace propiedades desconocidas se romperá en nuestra siguiente entrega, y eso es evitable.

• Un endpoint nuevo.
• Un parámetro de petición opcional nuevo.
• Un campo nuevo en una respuesta existente.
• Un valor nuevo en un enum que solo lees.
• Un tipo de evento de webhook nuevo.
• Relajar una regla de validación que antes rechazaba algo.

Qué exige una revisión nueva

Todo lo que pueda romper un cliente correcto recibe una revisión con fecha nueva. Tu revisión fijada sigue comportándose como está documentado.

• Quitar o renombrar un endpoint, un parámetro o un campo de respuesta.
• Cambiar el tipo o las unidades de un campo existente.
• Hacer obligatorio un parámetro opcional, o endurecer la validación.
• Cambiar el valor por defecto de un parámetro.
• Cambiar el significado de un valor de enum existente.
• Quitar un tipo de evento de webhook.

Obsolescencia

Cuando algo va camino de desaparecer sigue funcionando y empieza a anunciarse. Los endpoints obsoletos devuelven:

Deprecation: true
Sunset: Wed, 01 Jul 2026 00:00:00 GMT
Link: <https://skautik.com/docs/developers/api/properties>; rel="deprecation"

• Al menos 12 meses entre el aviso de obsolescencia y la retirada, para cualquier cosa que esté en una revisión publicada.
• Escribimos por correo al contacto técnico de la organización cuando empieza una obsolescencia, y de nuevo según se acerca la retirada, en lugar de confiar en que leas un registro de cambios.
• Pon una alerta sobre la cabecera Deprecation en tu propia monitorización. Es el aviso más temprano posible y vigilarlo no cuesta nada.

Escribir un cliente duradero

• Fija la revisión de forma explícita en lugar de confiar en el valor por defecto de tu cuenta.
• Ignora los campos y los valores de enum desconocidos en lugar de fallar por ellos.
• Trata los identificadores como cadenas opacas; no parsees nunca un prefijo buscando significado.
• No dependas del orden de los campos, de la ausencia de un campo, ni de un recuento que la API no promete.
• Ramifica según los códigos de error, no según la prosa del error.