Compatibilidad y versiones

La versión de la API de DUST se indica en la ruta: todos los endpoints se encuentran bajo /api/v1. Dentro de una versión, desarrollamos la API continuamente, pero siguiendo reglas estrictas: los cambios son aditivos de forma predeterminada, cualquier cambio que pudiera afectar a una integración que cumpla las prácticas recomendadas pasa primero por un periodo de obsolescencia y la especificación OpenAPI publicada constituye la definición oficial del contrato en todo momento.

Esta página define qué significa que su integración «cumpla las prácticas recomendadas» y qué prometemos a cambio.

Qué puede cambiar sin previo aviso

Estos cambios se consideran compatibles con versiones anteriores. Pueden aparecer en cualquier versión publicada y su integración debe tolerarlos:

• Nuevos endpoints y nuevas operaciones en rutas existentes.
• Nuevos parámetros de solicitud, encabezados y campos del cuerpo opcionales. Las solicitudes existentes siguen funcionando sin cambios.
• Nuevos campos en las respuestas. Los objetos se amplían con el tiempo.
• Nuevos valores en campos enumerados: se añaden nuevos tipos de eventos, estados y clases a medida que crece el producto.
• Nuevos códigos de error para modos de fallo que antes se comunicaban mediante un código genérico.
• Documentación, texto de error de message y orden de los campos. Las cadenas legibles para las personas no forman parte del contrato; el orden de los miembros de JSON nunca es significativo.

Cómo escribir una integración que mantenga la compatibilidad

Las reglas anteriores son seguras si su cliente sigue la práctica estándar de lectura tolerante:

• Ignore los campos de respuesta que no reconozca. Nunca produzca un error debido a miembros inesperados ni utilice una validación estricta del esquema que rechace campos desconocidos.
• Tolere valores de enumeración desconocidos. Ramifique según los valores que gestione y continúe correctamente con los que no gestione.
• Ramifique según el code del error, nunca según el message. Los códigos son identificadores estables; los mensajes están localizados y pueden reformularse. Consulte Convenciones de solicitud.
• Trate los ID y los cursores de paginación como cadenas opacas. Consérvelos y reutilícelos; nunca los analice ni los construya.
• Utilice únicamente lo que documente la especificación publicada. Los endpoints, campos y comportamientos que no figuren en la especificación OpenAPI pública no cuentan con ninguna garantía de compatibilidad.

Una integración que siga estas reglas no se verá afectada por los cambios aditivos y es el tipo de integración que protegen las garantías siguientes.

Qué consideramos un cambio incompatible

No realizamos ninguna de las acciones siguientes en una operación /api/v1 publicada sin aplicar el proceso de obsolescencia descrito más adelante:

• Eliminar o cambiar el nombre de un endpoint, un parámetro de solicitud o un campo de respuesta.
• Cambiar el tipo o el formato de un campo.
• Hacer obligatorio un dato de entrada de solicitud opcional o restringir los valores que acepta.
• Eliminar un valor de un campo enumerado.
• Cambiar el code de error o el estado HTTP devuelto para un modo de fallo existente y documentado.
• Exigir un nivel de autorización superior o un permiso nuevo para una operación existente.
• Cambiar sustancialmente la semántica de una operación, aunque su estructura no cambie.

Obsolescencia

Cuando necesitamos retirar o reestructurar algo, primero lo marcamos como obsoleto:

• La operación o el campo se marca como deprecated: true en la especificación OpenAPI publicada y la obsolescencia se indica en esta documentación.
• La funcionalidad obsoleta sigue funcionando sin cambios durante al menos 90 días desde el anuncio.
• Siempre que exista, habrá disponible un reemplazo documentado antes de la obsolescencia o en el momento de marcarla.

Observe la especificación, no los datos transmitidos

La especificación OpenAPI publicada en /openapi.json siempre refleja el contrato vigente, incluidos los marcadores de obsolescencia. Compararla entre las revisiones de su integración es la forma más fiable de ver qué ha cambiado.

Versiones

Las versiones principales nuevas son poco frecuentes por diseño. /api/v1 evoluciona de forma aditiva; solo introduciríamos una versión /api/v2 para una reestructuración que no pudiera realizarse de forma compatible y, en ese caso, /api/v1 seguiría siendo compatible durante un periodo de migración prolongado y anunciado explícitamente; nunca se eliminaría conforme al periodo de obsolescencia indicado anteriormente.

Véase también

• Convenciones de solicitud — el contrato de solicitud compartido al que se aplican estas garantías.
• Autenticación y claves de API — cuentas de servicio y periodos de vigencia de los tokens.
• Referencia completa de la API — generada a partir de la especificación publicada.