Ao projetar e construir uma integração de API, é fácil ficar tão focado nos detalhes de operações, atributos e parâmetros que você deixa de considerar fatores que podem impactar significativamente o desempenho, a estabilidade e a manutenção de sua integração.
Dar a esses fatores a atenção que eles merecem pode significar a diferença entre uma integração não confiável e uma muito sólida. Para garantir que sua integração seja a melhor possível, recomendamos incorporar estas quatro práticas recomendadas da API do Smartsheet:
1. Seja eficiente: use operações habilitadas para “volume”
Para eficiência máxima, use operações de API habilitadas para volume sempre que possível. Uma operação de API habilitada para volume permite adicionar, atualizar ou excluir vários itens usando uma única solicitação de API.
Por exemplo, se você precisar atualizar 10 linhas em uma planilha, faça isso usando uma única solicitação Atualizar linhas, em vez de executar 10 solicitações separadas (uma para cada linha).
As operações habilitadas para volume melhoram a eficiência reduzindo drasticamente o número de chamadas de saída que sua integração precisa fazer. Isso reduz suas chances de atingir o limite de taxa (uma vez que cada operação em massa conta como apenas uma solicitação para o limite).
Atualmente, as seguintes operações de API permitem que você conclua as seguintes tarefas em massa:
Adicionaremos mais operações habilitadas para “volume” no futuro, portanto, fique atento a essas oportunidades adicionais para melhorar a eficiência. E lembre-se, é uma prática recomendada fazer as coisas em massa sempre que possível.
Dica: permitir sucesso parcial
Normalmente, quando um erro é gerado durante uma operação em massa, o comportamento padrão é que toda a operação falhe. Por exemplo, se você fizer uma solicitação para atualizar linhas e um dos objetos de linha na solicitação for inválido, toda a operação falhará e nenhuma das linhas será atualizada.
No entanto, você tem a opção de permitir sucesso parcial em solicitações em massa. Permitir o sucesso parcial possibilitará que as partes bem-sucedidas de uma solicitação sejam executadas, mesmo se houver erros lançados durante a operação.
2. Seja prático: siga as diretrizes de limitação de taxa
Lidar com o erro “limite de taxa excedido”
A API do Smartsheet atualmente impõe um limite de taxa de 300 solicitações por minuto por token de acesso.
Certas operações com uso intensivo de recursos, como anexar um arquivo ou obter o histórico da célula, contam como 10 solicitações em relação ao limite de taxa. Se você exceder esse limite de taxa, as solicitações de API subsequentes (dentro de um período de um minuto) retornarão um código de status HTTP 429, juntamente com o seguinte corpo de resposta JSON:
{
“errorCode”: 4003,
“message”: “Rate limit exceeded.”
}
Recomendamos projetar sua integração para lidar elegantemente com esse erro de limite de taxa. Uma maneira de fazer isso é colocar sua integração em hibernação por 60 segundos quando o erro for encontrado e, posteriormente, repetir a solicitação.
Como alternativa, você pode optar por implementar a retirada exponencial, uma estratégia de tratamento de erros em que você repete periodicamente uma solicitação com falha com tempos de espera progressivamente mais longos entre as tentativas, até que a solicitação seja bem-sucedida ou um determinado número de tentativas seja alcançado.
Evite executar atualizações em “tiro rápido”
Além disso, recomendamos fortemente que você evite executar solicitações de API rápida e seguidamente para atualizar um objeto específico do Smartsheet repetidas vezes em um período muito curto de tempo.
Por exemplo, se a única coisa que sua integração faz é executar uma solicitação de atualização de linhas uma vez a cada segundo para a mesma planilha, isso equivaleria a um total de 60 solicitações por minuto — bem dentro das diretrizes de limitação de taxa.
No entanto, atualizar o mesmo objeto em uma sucessão tão rápida pode resultar em erros de salvamento que afetam negativamente sua integração e a experiência do usuário na plataforma Smartsheet.
Para evitar esse cenário, projete sua integração para que as solicitações de API nunca sejam executadas rápida e seguidamente no mesmo objeto do Smartsheet. Para máxima eficiência, considere agrupar as alterações e enviá-las em uma única solicitação usando uma operação habilitada para “volume” (por exemplo, Atualizar Linhas ou Adicionar Colunas).
Executar solicitações em série
Também desaconselhamos a execução de várias solicitações de API em paralelo para atualizar um objeto específico do Smartsheet. Fazer isso resultará em desempenho reduzido e, provavelmente, em erros devido a colisões de salvamento.
Para evitar esse cenário, projete sua integração de forma que as solicitações de API para atualizar um objeto específico do Smartsheet sejam sempre executadas em série: execute uma solicitação por vez e não inicie a próxima até que a solicitação anterior seja concluída.
3. Seja inteligente: lide com os erros de forma adequada
Uma solicitação de API bem-sucedida resultará em um código de status HTTP 200, juntamente com dados no corpo da resposta de acordo com a operação executada. Mas o que acontece se algo der errado e você receber uma resposta diferente de HTTP 200? A capacidade de lidar com erros de forma adequada é um componente crítico de uma integração API de qualidade.
Se uma solicitação de API do Smartsheet não for bem-sucedida, a API retornará um código de status HTTP 4xx ou 5xx, juntamente com um corpo de resposta JSON que especifica detalhes sobre o erro ocorrido. Por exemplo, se você executar uma solicitação GET Sheet usando uma ID de planilha inválida (inexistente), a resposta retornará um código de status HTTP 404 com o seguinte corpo de resposta JSON:
{
“errorCode”: 1006,
“message”: “Not Found”
}
Quando você deve tentar novamente?
Uma estratégia bem-sucedida de tratamento de erros requer que sua integração reconheça a diferença entre os erros que podem ser resolvidos tentando a solicitação novamente e os erros que nunca devem ser repetidos automaticamente.
O código de status HTTP retornado com uma resposta é sua primeira indicação quanto ao resultado da solicitação.
Recomendações de tratamento de erros
Além do código de status HTTP, você também deve avaliar o código de erro específico do Smartsheet que é retornado no corpo da resposta para qualquer solicitação malsucedida. Por exemplo:
{
“errorCode”: 1006,
“message”: “Not Found”
}
A documentação da API especifica recomendações de tratamento de erros para cada código de erro específico do Smartsheet. Recomendamos que você use essas informações para implementar a lógica de tratamento de erros de acordo com as seguintes diretrizes:
-
Se o código de erro indicar uma condição de erro permanente, não repita a solicitação.
-
Se o código de erro indicar um problema que pode ser corrigido, não repita a solicitação até que o problema seja corrigido.
-
Se o código de erro indicar um problema que pode ser resolvido repetindo a solicitação após um período de tempo, repita a solicitação usando backoff exponencial.
4. Seja diligente: implemente registros
Em um mundo ideal, sua integração funcionaria perfeitamente desde o primeiro dia e nunca haveria necessidade de solucionar qualquer tipo de problema.
Infelizmente, isso é raro. Quando surgem problemas, é importante que sua integração seja capaz de registrar solicitações e respostas de API.
Ter acesso às solicitações e respostas brutas (incluindo códigos de erro detalhados e mensagens de erro) quando surgirem problemas de API simplificará a solução de problemas e acelerará o tempo de resolução.
Os exemplos a seguir mostram o tipo de informação que seu aplicativo deve registrar para solicitações e respostas de API:
Request: verb, URI, header(s), request body
POST https://api.smartsheet.com/2.0/sheets/4098273196697476/columns
Authorization: Bearer MY_TOKEN
Content-Type: application/json
Request body:
[
{
"title": "FIRST COLUMN - My New Column",
"index": 0,
"type": "TEXT_NUMBER"
},
{
"title": "FIRST COLUMN - My New Column",
"index": 1,
"type": "TEXT_NUMBER"
}
]
Response: HTTP status code, response body
HTTP status: 400 Bad Request
Response body:
{
"errorCode": 1133,
"message": "Column titles are not unique among input columns.",
"detail": {
"columnTitle": "FIRST COLUMN - My New Column"
}
}
Muitas vezes, ter acesso a essas informações permitirá que você identifique e resolva o problema por conta própria. Em ocasiões em que não for esse o caso, você pode entrar em contato com devrel@smartsheet.com para obter assistência. Pediremos as informações de solicitação/resposta acima para solucionar o problema.
Você deve implementar o registro de solicitação e resposta da API ao configurar sua integração pela primeira vez, pois isso tornará a experiência mais eficiente.
Comece a construir sua integração
Não importa se você está no processo de projetar e construir uma integração com o Smartsheet ou se já construiu uma integração anteriormente, a hora de incorporar as melhores práticas que abordamos neste post é agora.
Além disso, encorajamos você a aproveitar ao máximo o Portal do desenvolvedor Smartsheet para obter recursos e orientações discutidos nesta postagem, todos com o objetivo de ajudar a acelerar o tempo necessário para você se familiarizar com a API do Smartsheet e ajudá-lo a implantar sua solução com confiança.
Inscreva-se no Boletim informativo de TI do Smartsheet para obter dicas, estratégias e ideias focadas em ajudar os profissionais de TI a aumentar seu impacto nos negócios.