Melhores práticas de API REST

Você deve se inscrever em eventos de webhook em vez de fazer polling na API para obter dados. Isso ajudará sua integração a permanecer dentro do limite de taxa da API. Para mais informações, consulte Como configurar a integração de Webhooks com o Fluid Boards

Para evitar exceder os limites de taxa secundários, você deve fazer requisições em série em vez de simultaneamente. Para isso, você pode implementar um sistema de fila para as requisições.

Se você estiver fazendo um grande número de requisições POST, PATCH, PUT ou DELETE, aguarde pelo menos um segundo entre cada requisição. Isso ajudará você a evitar limites de taxa secundários.

Se você receber um erro de limite de taxa, deve parar de fazer requisições temporariamente de acordo com estas diretrizes:

• Se o cabeçalho de resposta x-ratelimit-reset estiver presente, você não deve repetir sua requisição até após o timestamp.

• Se o cabeçalho x-ratelimit-remaining for 0, você não deve fazer outra requisição até após o horário especificado pelo cabeçalho x-ratelimit-reset. O cabeçalho x-ratelimit-reset está no formato padrão ISO 8601 para data e hora.

• Caso contrário, aguarde pelo menos um minuto antes de tentar novamente. Se sua requisição continuar falhando devido a um limite de taxa secundário, aguarde um tempo exponencialmente crescente entre as tentativas e lance um erro após um número específico de tentativas.
  

A API REST do Fluid usa redirecionamento HTTP quando apropriado. Você deve assumir que qualquer requisição pode resultar em um redirecionamento. Receber um redirecionamento HTTP não é um erro, e você deve seguir o redirecionamento.

Um código de status 301 indica redirecionamento permanente. Você deve repetir sua requisição para a URL especificada pelo cabeçalho location. Além disso, você deve atualizar seu código para usar essa URL em requisições futuras.

Um código de status 302 ou 307 indica redirecionamento temporário. Você deve repetir sua requisição para a URL especificada pelo cabeçalho location. No entanto, você não deve atualizar seu código para usar essa URL em requisições futuras.

Outros códigos de status de redirecionamento podem ser usados de acordo com as especificações HTTP.

Muitos endpoints da API retornam valores de URL para campos no corpo da resposta. Você não deve tentar analisar essas URLs ou prever a estrutura de URLs futuras. Isso pode fazer com que sua integração quebre se o Fluid alterar a estrutura da URL no futuro.

Em vez disso, você deve procurar um campo que contenha as informações de que precisa. Por exemplo, o endpoint para criar uma Action retorna um campo url com um valor como https://organisation.fluid.work/rest/api/action/1347 e um campo id com um valor como 1347. Se você precisar saber o id da issue, use este campo em vez de analisar o 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"
}

Você não deve ignorar códigos de erro 4xx e 5xx repetidos. Em vez disso, você deve garantir que está interagindo corretamente com a API. Por exemplo, se um endpoint solicita uma string e você está passando um valor numérico, você receberá um erro de validação. Da mesma forma, tentar acessar um endpoint não autorizado ou inexistente resultará em um erro 4xx.