Al diseñar y crear una integración con API, es fácil centrarse demasiado en los detalles de las operaciones, atributos y parámetros, y no considerar los factores que podrían afectar significativamente el rendimiento, la estabilidad y el mantenimiento de la integración.
Prestarle la atención justa a esos factores puede marcar la diferencia entre una integración que no es confiable y otra que es completamente estable y sólida. Para garantizar que la integración sea la mejor posible, recomendamos firmemente incorporar estas cuatro prácticas recomendadas para la API de Smartsheet:
1. Sea eficiente: use operaciones que se pueden procesar en forma masiva
Para lograr la máxima eficiencia, use operaciones de la API que se puedan procesar en forma masiva siempre que sea posible. Una operación de la API que se puede procesar en forma masiva permite agregar, actualizar o borrar varios artículos con una sola solicitud a la API.
Por ejemplo, si tiene que actualizar 10 filas en una hoja, hágalo con una sola solicitud Actualizar filas en lugar de ejecutar diez solicitudes por separado (una para cada fila).
Las operaciones que se pueden procesar en forma masiva mejoran la eficiencia porque reducen considerablemente la cantidad de llamadas salientes que su integración tiene que hacer. Esto también reduce las posibilidades de alcanzar el límite de velocidad (porque cada operación en forma masiva cuenta como solo una solicitud para el límite).
Las siguientes operaciones con la API le permiten completar las tareas siguientes en forma masiva:
Agregaremos más operaciones que se pueden procesar en forma masiva en el futuro; por eso, manténgase al tanto de esas oportunidades adicionales de mejorar la eficiencia. Y recuerde, se recomienda hacer las cosas en forma masiva siempre que sea posible.
Consejo: Permitir los éxitos parciales
Cuando se genera un error durante una operación en forma masiva, el comportamiento predeterminado suele ser que toda la operación falló. Por ejemplo, si hace una solicitud de Actualizar filas y uno de los objetos de la fila en la solicitud no es válido, toda la operación fallará y ninguna de las filas se actualizará.
Sin embargo, tiene la opción de permitir el éxito parcial en las solicitudes masivas. Permitir el éxito parcial hará que las partes correctas de la solicitud se lleven a cabo incluso aunque haya errores durante la operación.
2. Practicidad: respete los lineamientos del límite de velocidad
Solucione el error "se superó el límite de velocidad"
La API de Smartsheet tiene un límite de velocidad de 300 solicitudes por minuto por token de acceso.
Ciertas operaciones con muchos recursos, como adjuntar un archivo u obtener el historial de la celda, cuentan como 10 solicitudes para el límite de velocidad. Si este límite de velocidad se supera, las solicitudes a la API posteriores (dentro de un período de un minuto) arrojarán un código de estado 429 HTTP, junto con el siguiente cuerpo de la respuesta de JSON:
{
“CódigoError”: 4003,
“mensaje”: “Se superó el límite de velocidad”.
}
Le recomendamos que diseñe su integración para poder manejar fácilmente este error de límite de velocidad. Una manera de lograrlo es que la integración quede en suspensión durante 60 segundos cuando encuentra el error y, luego, volver a intentar la solicitud.
También, puede implementar un retroceso exponencial, una estrategia para el control de errores en la que intenta regularmente una solicitud no superada con tiempos de espera cada vez más largos entre los reintentos, hasta que la solicitud se realice correctamente o hasta que se alcance cierto número de reintentos.
Evite ejecutar actualizaciones "rapid fire"
Además, recomendamos firmemente que evite ejecutar solicitudes a la API muy rápidas y seguidas para actualizar un objeto específico de Smartsheet muchas veces en un período breve.
Por ejemplo, si lo único que hace su integración es ejecutar la solicitud Actualizar filas una vez por segundo para la misma hoja, sería un total de 60 solicitudes por minuto, dentro de los lineamientos del límite de velocidad.
Sin embargo, actualizar el mismo objeto en una sucesión rápida podría generar errores de guardado que afecten negativamente la integración y la experiencia del usuario dentro de la plataforma de Smartsheet.
Para evitar este escenario, diseñe su integración de manera que las solicitudes a la API nunca se ejecuten con una sucesión rápida para el mismo objeto de Smartsheet. Para lograr una máxima eficiencia, considere agrupar los cambios y enviarlos en una sola solicitud con una operación que se pueda procesar en forma masiva (p. ej., Actualizar filas o Agregar columnas).
Ejecute las solicitudes en serie
Sugerimos firmemente que no se ejecuten varias solicitudes a la API en paralelo para actualizar un objeto específico de Smartsheet. Hacerlo reducirá el rendimiento y, probablemente, genere errores debido a las colisiones de guardado.
Para evitar este escenario, diseñe la integración de manera tal que las solicitudes a la API que actualicen un objeto específico de Smartsheet siempre se ejecuten en serie: ejecute una solicitud por vez y no comience la próxima solicitud hasta que la anterior se haya completado.
3. Sea inteligente: controle los errores de manera adecuada
Una solicitud a la API correcta tendrá un código de estado 200 HTTP, junto con los datos en el cuerpo de la respuesta según la operación realizada. ¿Qué pasa si algo sale mal y obtiene otra respuesta que no sea la 200? La posibilidad de controlar errores de manera adecuada es un componente fundamental de una integración de calidad con la API.
Si una solicitud a la API de Smartsheet no es correcta, la API devuelve un código de estado 4xx o 5xx HTTP, junto con el cuerpo de la respuesta de JSON que especifica los detalles sobre el error que se produjo. Por ejemplo, si ejecuta una solicitud OBTENER hoja con una id. de hoja no válida (inexistente), la respuesta devolverá un código de estado HTTP 404 con el cuerpo de la respuesta de JSON siguiente:
{
“CódigoError”: 1006,
“mensaje”: “No encontrado”
}
¿Cuándo se debe reintentar?
Una estrategia de control de errores correcta requiere que la integración reconozca la diferencia entre los errores que se podrían resolver al reintentar la solicitud y los errores que nunca se deberían reintentar automáticamente.
El código de estado HTTP devuelto con una respuesta es la primera indicación del resultado de la solicitud.
Recomendaciones para el control de errores
Además del código de estado HTTP, también debería evaluar el código de error específico de Smartsheet devuelto en el cuerpo de la respuesta para las solicitudes no satisfactorias. Por ejemplo:
{
“CódigoError”: 1006,
“mensaje”: “No encontrado”
}
La documentación de la API especifica las recomendaciones para el control de errores para cada código de error específico de Smartsheet. Le recomendamos que use esa información para implementar la lógica del control de errores según los lineamientos siguientes:
-
Si el código de error indica una condición de error permanente, no reintente la solicitud.
-
Si el código de error indica un problema que se puede solucionar, no reintente la solicitud hasta que el problema esté solucionado.
-
Si el código de error indica un problema que se podría solucionar reintentado la solicitud después de un tiempo, reintente la solicitud con el retroceso exponencial.
4. Sea diligente: implemente el registro
En un mundo ideal, la integración funcionaría sin inconvenientes desde el día uno y nunca surgirían problemas de ningún tipo para solucionar.
Desafortunadamente, rara vez pasa esto. Cuando los problemas aparecen, es importante que la integración pueda registrar las solicitudes y las respuestas de la API.
Tener acceso a las solicitudes y respuestas sin procesar (que incluye los códigos de error y los mensajes de error detallados) cuando surjan problemas en la API agilizará resolución de problemas y reducirá el tiempo que se demora para resolverlos.
Los siguientes ejemplos muestran el tipo de información que la aplicación debería registrar para las solicitudes y respuestas de la API:
Solicitud: verbo, URI, encabezado(s), cuerpo de la solicitud
PUBLICACIÓN https://api.smartsheet.com/2.0/sheets/4098273196697476/columns
Autorización: Portador MI_TOKEN
Tipo de contenido: aplicación/json
Cuerpo de la solicitud:
[
{
"título": "PRIMERA COLUMNA - Mi nueva columna",
"índice": 0,
"tipo": "TEXTO_NÚMERO"
},
{
"título": "PRIMERA COLUMNA - Mi nueva columna",
"índice": 1,
"tipo": "TEXTO_NÚMERO"
}
]
Respuesta: código de estado HTTP, cuerpo de la respuesta
Estado HTTP: 400 Solicitud incorrecta
Cuerpo de la respuesta:
{
"CódigoError": 1133,
"mensaje": "Los títulos de las columnas no son únicos entre las columnas de entrada.”,
"detalle": {
"TítuloColumna": "PRIMERA COLUMNA - Mi nueva columna"
}
}
A menudo, tener acceso a esta información le permitirá identificar y resolver el problema por su cuenta. Si no logra resolverlo, puede comunicarse con devrel@smartsheet.com para obtener ayuda. Le pediremos la información de solicitud/respuesta anterior para poder resolver el problema.
Debería implementar el registro de las solicitudes y respuestas de la API la primera vez que configura la integración, ya que hará que la experiencia sea más eficiente.
Comience a crear su integración
Ya sea que esté en el proceso de diseñar y crear una integración con Smartsheet o que ya la haya creado, no hay un momento mejor que ahora para incorporar las mejores prácticas que tratamos en esta publicación.
Además, le alentamos a aprovechar al máximo el Portal para desarrolladores de Smartsheet, donde encontrará los recursos y las guías que analizamos en esta publicación que le ayudarán a acelerar el tiempo que le lleva familiarizarse con la API de Smartsheet y a sentir que su solución ya está lista para la implementación.
Suscríbase al Boletín de TI de Smartsheet para obtener consejos, estrategias e ideas centradas en ayudar a los profesionales de TI a mejorar sus negocios.