Última actualización: 31 de enero de 2024
Tulip proporciona un conjunto de API públicas que permiten a los usuarios interactuar mediante programación con la plataforma Tulip . Tulip organiza sus API en grupos denominados Namespaces, que representan a grandes rasgos áreas funcionales del producto Tulip (por ejemplo, Apps, Automatizaciones, Usuarios, etc.). Cada Namespace API recibe una etiqueta denominada versión (de la forma "v1", "v2", "v3", etc.). Todos los puntos finales de la API contenidos en un espacio de nombres se versionan juntos como una unidad.
A medida que Tulip desarrolle nuevas funciones, mejore las existentes y solucione problemas, es posible que publiquemos actualizaciones de estas API que cambien una versión existente de la API o introduzcan una nueva versión de la API (las normas que dictan qué tipos de cambios requieren una nueva versión se describen en la sección Estabilidad ). Las actualizaciones de la API se lanzan con cada versión de la plataforma Tulip y se describirán en las notas de la versión de Tulip. En un momento dado pueden estar disponibles varias versiones de un determinado espacio de nombres. Se recomienda a los usuarios que utilicen la versión más actualizada de las API, pero las versiones anteriores se mantienen durante un tiempo (para más información sobre el ciclo de vida de las versiones, consulte la sección Soporte ). Todos los derechos de uso de las API de Tulip son los establecidos en el Acuerdo de licencia de API deTulip.
Estabilidad
Cuando una versión de un espacio de nombres de la API Tulip se considera estable, Tulip puede publicar cambios en la API, pero dichos cambios deben ser compatibles con versiones anteriores. En el contexto de las API de Tulip , un cambio se considera generalmente compatible con versiones anteriores si no rompe la funcionalidad de las integraciones existentes que utilizan esa API. En concreto, los siguientes tipos de cambios se consideran compatibles con versiones anteriores:
Añadir un nuevo punto final a un espacio de nombres.
Añadir un campo opcional del cuerpo de la solicitud, un parámetro de consulta o una cabecera HTTP, de forma que el significado de otros campos, parámetros o cabeceras no se modifique cuando se omita el campo opcional. Tenga en cuenta que los campos no reconocidos de los cuerpos de petición se suelen ignorar, por lo que un campo que antes no tenía significado (lo que no causaría un error) puede ganar significado en una versión posterior sin que se considere un cambio de ruptura.
Añadir un tipo de contenido de cuerpo de solicitud aceptado a un punto final. Si el nuevo tipo de contenido representa datos estructurados (JSON, YAML, CSV, etc.), debe adherirse a la estructura documentada del cuerpo de la solicitud. Si el nuevo tipo de contenido representa datos no estructurados (imagen, vídeo, PDF, texto sin formato, otros datos binarios), debe adherirse a cualquier restricción documentada en la descripción del cuerpo de la solicitud.
Cambiar el tipo o las reglas de validación de un campo del cuerpo de la solicitud, un parámetro de consulta o un encabezado HTTP de forma que todos los valores válidos anteriormente sigan considerándose válidos.
Añadir un nuevo campo de cuerpo de respuesta o cabecera HTTP.
Añadir un nuevo código de estado HTTP de respuesta de error (4xx, 5xx).
Eliminación de posibles valores del tipo de un campo del cuerpo de la respuesta o de una cabecera HTTP, de forma que el significado de otros campos o cabeceras de respuesta no se modifique.
Cambiar la documentación de un tipo, código de error, campo o punto final de forma que no afecte al comportamiento de la API.
Modificación del texto de la descripción del error presentada en las respuestas de error.
Cambiar los nombres de visualización u otros contenidos textuales de cualquier recurso definido por Tulip.
Modificación de los límites de velocidad, tamaño o recuento de recursos impuestos a los puntos finales.
Corrección de un error para alinear el comportamiento real de un punto final con su comportamiento documentado.
Solucionar una vulnerabilidad de seguridad por cualquier medio necesario, incluso con cambios que de otro modo se considerarían rupturistas. En el caso de que Tulip necesite publicar una corrección de seguridad crítica que resulte en un cambio rompedor de la API, intentaremos trabajar con nuestros clientes para actualizar sus integraciones y evitar el tiempo de inactividad en la medida de lo posible.
Añadir, eliminar o cambiar cualquier punto final, parámetro o tipo que no esté documentado públicamente.
Ocasionalmente, Tulip puede necesitar publicar un cambio en una API que no sea compatible con versiones anteriores. Esto se conoce como un cambio de ruptura o un cambio incompatible con versiones anteriores. Tulip sólo publicará cambios de ruptura en las API estables en una nueva versión de su espacio de nombres de API (a excepción de las correcciones de seguridad críticas, como se ha descrito anteriormente). Los siguientes tipos de cambios se consideran incompatibles con versiones anteriores:
Eliminación de un punto final de un espacio de nombres.
Eliminar un campo del cuerpo de la solicitud, un parámetro de consulta o una cabecera HTTP.
Eliminación de un tipo de contenido de cuerpo de solicitud aceptado de un punto final.
Cambio del tipo de contenido del cuerpo de respuesta de un punto final.
Cambiar el tipo o las reglas de validación de un campo del cuerpo de la solicitud, un parámetro de consulta o un encabezado HTTP de forma que algunas entradas ya no se consideren válidas.
Cambiar el valor predeterminado de un campo opcional del cuerpo de la solicitud, un parámetro de consulta o una cabecera HTTP.
Añadir un campo obligatorio del cuerpo de la solicitud, un parámetro de consulta o una cabecera HTTP.
Añadir un campo opcional del cuerpo de la solicitud, un parámetro de consulta o una cabecera HTTP de forma que el significado de cualquier otro campo, parámetro o cabecera también se modifique.
Añadir valores posibles al tipo de un campo de cuerpo de respuesta o cabecera HTTP.
Añadir un nuevo código de estado HTTP de respuesta de éxito (1xx, 2xx, 3xx).
Eliminar un campo del cuerpo de la respuesta o una cabecera HTTP.
Cambiar significativamente la semántica o funcionalidad documentada de un punto final, incluso si la interfaz no se modifica.
Límites
La API Tulip aplica varios tipos de límites con el fin de proteger los recursos compartidos (servidores API, bases de datos, etc.) de una carga excesiva que pueda afectar a la calidad del servicio para otros usuarios y otros clientes. Dichos límites incluyen (son sólo ejemplos ilustrativos):
Límites de velocidad: Por defecto, un cliente determinado no puede realizar peticiones a un punto final dado más de un cierto número de veces por segundo.
Límites de tamaño: El nombre de un recurso no puede superar un determinado número de caracteres, o el tamaño de un archivo cargado no puede superar un determinado tamaño de archivo.
Límites de recuento de recursos: No se puede crear más de un número determinado de espacios de trabajo.
Aunque Tulip puede proporcionar documentación sobre algunos de estos límites, no se consideran parte de la API estable y pueden cambiar en cualquier momento en función de las condiciones de carga actuales, la evolución de los requisitos del producto, las preferencias de los usuarios y otros factores. Los clientes deben utilizar la información proporcionada por las respuestas de la API Tulip (códigos de estado, códigos de error y campos de error) para gestionar los errores de limitación. Tulip se reserva el derecho de desactivar a los clientes que incumplan repetidamente estos límites.
Apoye
Tulip proporciona un soporte para sus API similar al que proporcionamos para otros productos de Tulip . El soporte completo incluye el mantenimiento de la documentación, la respuesta a preguntas, la resolución de problemas, la publicación de correcciones de errores y la publicación de correcciones de seguridad para estas API. Tulip no proporciona soporte para API no documentadas. El nivel de soporte que Tulip proporciona para una versión pública de API Namespace varía en función de cómo esté etiquetada en la documentación de la API:
Alfa - Tulip proporcionará un soporte limitado para esta API y podrá lanzar cambios de última hora en la misma en cualquier momento.
Beta - Tulip apoya plenamente esta API, pero puede lanzar cambios de ruptura a esta API en cualquier momento. Comunicaremos cualquier cambio de última hora a los clientes de la versión Beta.
Estable - Tulip apoya plenamente esta API y la considera estable, tal y como se define en la sección Estabilidad.
Obsoleta - Tulip tiene la intención de eliminar esta API en un futuro próximo. Tulip proporcionará soporte completo para esta API, pero los usuarios deben planificar la actualización de cualquier integración que la utilice a una versión más reciente de la API, para la que Tulip proporcionará orientación. Por lo general, las API obsoletas no recibirán actualizaciones, salvo correcciones críticas de seguridad o errores.
Fin de soporte - Tulip no proporcionará ningún soporte para esta API, incluidas las correcciones críticas de seguridad. Las API no compatibles pueden dejar de funcionar en cualquier momento sin previo aviso.
Los espacios de nombres de API estables permanecerán estables durante al menos un ciclo de versiones LTS antes de ser marcados como obsoletos. Los espacios de nombres de API obsoletos seguirán siendo compatibles durante al menos dos ciclos de versiones LTS antes de ser marcados como no compatibles.