Políticas de servicio
Introducción¶
En Desk estamos orientados a mejorar continuamente nuestro servicio al cliente, por esta razón permanentemente optimizamos nuestros canales de atención y ayuda, y rediseñamos los procesos que nos permiten responder con más rapidez y efectividad.
En este documento se detalla el acuerdo de nivel de servicio y especificaciones en cada Web Service (APIs) desarrollados para integrar sistemas de terceros.
Versiones actuales¶
En la siguiente tabla se muestran las versiones activas en nuestra API.
| Versión API | Fecha de lanzamiento | Estado |
|---|---|---|
| v1 | 1 de enero 2016 | deprecada |
| v2 | 1 de enero 2017 | activa |
A continuación se explica la implicancia de cada estado:
Activa: Con soporte completo. Está operativa y puede presentar versiones menores en el futuro.
Legacy: Aún operativa pero no tendrá actualizaciones. Candidata a eliminación próxima.
Deprecada: Sin soporte ni documentación. Esta versión de API ya no se encuentra operativa y es inminente su eliminación.
Eliminada: Esta versión de API ya no se encuentra operativa.
Versionamiento durante la operación del servicio web¶
Cada versión de API no recibirá cambios que afecten la especificación técnica original, solo correcciones de errores.
Las modificaciones se realizarán sobre nuevas versiones completas de la API, permitiendo asegurar continuidad y retro compatibilidad si su código consume la versión de API compatible.
Es normal que ocurran cambios en una API a lo largo del tiempo debido a distintos motivos:
- Se descubren errores.
- Se requiere más información en un servicio web.
- Se requiere la creación de nuevos servicios web.
- Se requiere modificar la información de un servicio web existente:
- Cambio de nombre de parámetros.
- Eliminación o incorporación de campos.
- Un campo ahora tiene información expandida.
- Se requiere eliminar un servicio web.
- Cambios en reglas de negocio que no modifiquen estructura pero si el significado de la información.
- La plataforma que alimenta la API ha cambiado su lógica de operación.
Para resolver lo anterior, la API de Desk disponible para clientes seguirá la siguiente nomenclatura en sus versiones:
Número de versión mayor: Representa que entre un número y otro existen cambios que rompen la operación de la API respecto a su predecesor. Si el número de versión es v2.1, el número de versión mayor corresponde a 2.
Número de versión menor: Representa que entre un número y otro existen cambios que no deben afectar el consumo de la API respecto a su predecesor y es seguro hacer la actualización. Si el número de versión es v2.1, el número de versión mayor corresponde a 1.
Si se desea actualizar a una versión v3.0 será necesario hacer cambios en su código fuente para poder cambiar a dicha versión. Por el contrario, una actualización a v2.2 indica que hay modificaciones en la API pero los cambios sí son retro compatibles.
¿Qué significa que un cambio sea retrocompatible o no?¶
Un cambio retro compatible implica que desde una versión a otra, se tiene la misma información, por ejemplo:
- Agregar nuevos endpoints disponibles en la API sin afectar los existentes.
- Agregar nuevos campos a una respuesta previa, sin afectar los anteriores.
- Incorporar más métodos HTTP a un endpoint (GET, POST, UPDATE, etc).
Es decir, es seguro actualizar desde v2 hacia v2.1 pues se asegura que la información que se consume en v2 también estará disponible en v2.1, pero como se explica en el párrafo anterior, la versión v2.1 sí puede contener cosas nuevas.
Cambios que rompen la API, es decir no son retrocompatibles son modificaciones que hacen que al cambiar de versión ya no se cuente con la misma información anterior, por ejemplo:
- Se requiere modificar la información de un servicio web existente:
- Cambio de nombre de parámetros.
- Eliminación de campos.
- Un campo ahora tiene información expandida.
- Se requiere eliminar un servicio web.
- Cambios en reglas de negocio que no modifiquen estructura pero si el significado de la información.
- La plataforma que alimenta la API ha cambiado su lógica de operación.
Es decir, si usted actualiza de v2.1 hacia v3, debe leer la guía de migración para enteder los cambios que podrían afectar su sistema.
Política de descontinuación y soporte de versiones¶
Cada vez que Desk prepare una nueva versión se avisará con anticipación su fecha de lanzamiento.
Durante el lanzamiento se indicará la lista de cambios que pueden afectar su servicio. Se indicará si la versión tiene cambios mayores o menores y se incluirá una guía de migración entre versiones.
Calendarización de descontinuación¶
Cambios a versión menor:¶
Cada vez que Desk lance una nueva versión menor, se darán 6 meses de soporte a la versión inmediatamente anterior durante 6 meses.
Transcurridos los 6 meses se dejará de entregar corrección de errores dedicados a esta versión, entrando en estado legacy.
A los 6 meses posteriores dicha versión de API pasa a estado deprecado y se perderá acceso a la documentación. En este punto es forzosamente es necesario actualizar al menos a la próxima versión más nueva ya que el servicio en esa versión puede terminar su funcionamiento, entrando a estado eliminado.
En resumen, se asegura mínimo 12 meses de operación para una versión v2.1 una vez se lance la versión v2.2.
Cambios a versión mayor:¶
Opera muy similar al proceso de cambio entre versión menor, pero los bloques de tiempo son de 8 meses y no 6.
A los 8 meses se dejará de entregar corrección de errores dedicados a la versión anterior previa entrando en estado denominado legacy.
A los 8 meses posteriores la API pasa a estado deprecado.
En resumen, se asegura mínimo 16 meses de operación para una versión v2.2 una vez se lance la versión v3.
El equipo de Desk analizará el consumo de sus servicios a la API, lo que nos permitirá conocer si su integración solicita una versión próxima a ser eliminada, permitiendo notificar oportunamente.
Además de la guía de migración, nuestros ingenieros estarán disponibles para consultas sobre cómo migrar sus servicios.
Bajo excepciones el plazo de deprecado a eliminado se puede extender.
Recomendaciones para el consumo de Desk API¶
Siempre utilice las llaves de los argumentos, no se base en el orden de los campos pues este no es garantizado.
Si recibe una respuesta con más información de la que utiliza debe ignorarla.
No realizar validaciones sobre la cantidad de campos, es posible que éstos aumenten en una versión menor y haga más difícil la migración entre versiones.