API | Bling - Boas práticas
Boas práticas Introdução Quando se está desenvolvendo uma solução onde precisa consumir uma API de terceiro, é essencial saber lidar com ela para obter o melhor desempenho possível, dentro das condições que ela pode oferecer, para não se deparar com erros que poderiam ser evitados. Recomendações Leia com atenção a documentação específica sobre a API que deseja implementar, para compreender todas as funcionalidades disponíveis para utilização. Na documentação, estarão descritos os objetivos de cada endpoint, método HTTP, filtros, schemas de dados detalhado e os códigos de retornos. Paginação A paginação é utilizada na obtenção de dados através do método GET. Para informar a página utilize o parâmetro pagina. Para controlar a quantidade de registros retornados na busca, utilize o parâmetro limite. Por padrão, serão retornados 100 registros por requisição, sendo possível configurar a quantidade de registros conforme exemplo abaixo: Atualização total (PUT) e parcial (PATCH) A API disponibiliza dois métodos para atualizar um recurso existente: PUT e PATCH, e eles têm comportamentos diferentes. O método PUT substitui o recurso por completo. Todos os campos que já possuem valor preenchido precisam ser informados no corpo da requisição, pois caso algum campo seja omitido será removido ou retornará ao valor padrão, sem possibilidade de recuperação. O método PATCH atualiza apenas os campos enviados no corpo da requisição. Os demais campos do recurso permanecem inalterados. Nesse exemplo, nome, tipo, situacao e formato são obrigatórios em toda chamada PUT. Qualquer outro campo do produto (como descricaoCurta ou marca) que não esteja no corpo da requisição será removido ou zerado. Já aqui, somente preco é alterado, mantendo os demais campos do produto como estavam. Atenção: nem todo endpoint possui o método PATCH. Verifique na documentação específica de cada recurso se a atualização parcial está disponível antes de assumir esse comportamento. Tratamento de erros Durante o desenvolvimento é possível encontrar erros não previstos. Em decorrência a isso, é importante se atentar às mensagens de erro. Verifique o código de estado HTTP, caso ele seja diferente de 2xx, construa um tratamento de erros que seja eficiente e condizente ao retorno obtido. Retornos com o HTTP code 4xx, são erros provenientes de validação, leia a mensagem de erro no corpo da resposta e verifique os dados enviados na requisição. Recomenda-se a criação de um ou mais componentes ou clientes REST para consumo da API. Segurança De acordo com as orientações na seção de autenticação, para maior segurança, as práticas abaixo são recomendadas:
  • Não deixe que mais alguém conheça o seu client_secret, access_token e nem do refresh_token.
  • Prefira gerar um state único para enviar na requisição e através dele valide a operação.
  • Garanta que a requisição para obter os tokens de acesso sejam feitas sempre server-to-server.
  • Sempre utilize o protocolo HTTPS nas requisições.