Buenas prácticas de la API REST

Debe suscribirse a eventos de webhook en lugar de sondear la API en busca de datos. Esto ayudará a que su integración se mantenga dentro del límite de tasa de la API. Para obtener más información, consulte Cómo configurar webhooks para la integración con Tableros de Fluid

Para evitar exceder los límites de tasa secundarios, debe realizar las solicitudes de forma secuencial en lugar de simultánea. Para lograrlo, puede implementar un sistema de cola para las solicitudes.

Si está realizando una gran cantidad de solicitudes POST, PATCH, PUT o DELETE, espere al menos un segundo entre cada solicitud. Esto le ayudará a evitar los límites de tasa secundarios.

Si recibe un error de límite de tasa, debe dejar de hacer solicitudes temporalmente según estas pautas:

• Si el encabezado de respuesta x-ratelimit-reset está presente, no debe reintentar su solicitud hasta después de la marca de tiempo indicada.

• Si el encabezado x-ratelimit-remaining es 0, no debe realizar otra solicitud hasta después de la hora especificada por el encabezado x-ratelimit-reset. El encabezado x-ratelimit-reset está en el formato estándar ISO 8601 para fecha y hora.

• De lo contrario, espere al menos un minuto antes de reintentar. Si su solicitud continúa fallando debido a un límite de tasa secundario, espere una cantidad de tiempo que aumente exponencialmente entre reintentos y genere un error después de un número específico de reintentos.
  

La API REST de Fluid utiliza redirección HTTP cuando corresponde. Debe asumir que cualquier solicitud puede dar como resultado una redirección. Recibir una redirección HTTP no es un error, y debe seguir la redirección.

Un código de estado 301 indica una redirección permanente. Debe repetir su solicitud a la URL especificada por el encabezado location. Además, debe actualizar su código para usar esta URL en futuras solicitudes.

Un código de estado 302 o 307 indica una redirección temporal. Debe repetir su solicitud a la URL especificada por el encabezado location. Sin embargo, no debe actualizar su código para usar esta URL en futuras solicitudes.

Es posible que se utilicen otros códigos de estado de redirección de acuerdo con las especificaciones HTTP.

Muchos endpoints de la API devuelven valores de URL para los campos del cuerpo de la respuesta. No debe intentar analizar estas URL ni predecir la estructura de futuras URL. Esto puede hacer que su integración deje de funcionar si Fluid cambia la estructura de la URL en el futuro.

En su lugar, debe buscar un campo que contenga la información que necesita. Por ejemplo, el endpoint para crear una Acción devuelve un campo url con un valor como https://organisation.fluid.work/rest/api/action/1347 y un campo id con un valor como 1347. Si necesita saber el id de la incidencia, utilice este campo en lugar de analizar el campo url.

{
    "fields": {
        "createDate": "2023-10-13T18:50:01.0000000",
        "description": "Description 1",
        "modifiedDate": "2023-10-13T18:50:01.0000000",
        "priority": "Medium",
        "status": "Request",
        "taskType": "Task",
        "title": "Title 1"
    },
    "id": 4206,
    "guid": "0d0fcfb6-b1d9-41b0-8264-b29ace60df63",
    "url": "https://client.fluid.work/rest/api/action/4206"
}

No debe ignorar los códigos de error 4xx y 5xx repetidos. En su lugar, debe asegurarse de que está interactuando correctamente con la API. Por ejemplo, si un endpoint espera un valor de tipo Texto y usted le pasa un valor numérico, recibirá un error de validación. De manera similar, intentar acceder a un endpoint no autorizado o inexistente dará como resultado un error 4xx.