Integrador de APIs

Orientações Gerais

Ao projetar uma API RESTful que segue estritamente as melhores práticas, é possível melhorar sua usabilidade, manutenibilidade e escalabilidade. Ao projetar operações CRUD para uma entidade de domínio, aqui estão algumas das melhores práticas a serem seguidas.

Use métodos HTTP adequadamente

"POST" para criar ou cadastrar um novo objeto ou registro na coleção;

"GET" para consultar, pesquisar e listar objetos;

"PUT" para atualizar um objeto quando o objetivo for substituir todo o recurso;

"PATCH" para atualizar um objeto, quando o objetivo for uma atualização parcial no recurso;

"DELETE" para deletar

Use Substantivos para Nomes de Recursos

Use substantivos no plural, para um recurso de usuário.

Evite verbos, pois o método HTTP (GET, POST, PUT, DELETE) já indica a ação.

Use o Caminho URL para Hierarquizar os Recursos:

Por exemplo, para acessar um pedido específico de um usuário: /usuarios/{userId}/pedidos/{orderId}.

Sempre Use HTTPS:

Para garantir que os dados em trânsito estejam criptografados e seguros, utilize códigos de status HTTP significativos

• 200 OK para requisições GET e PUT bem-sucedidas
• 201 Created para requisições POST bem-sucedidas
• 204 Sem conteúdo, caso DELETE tenha sucesso
• 400 Solicitação inválida para requisições inválidas
• 401 Não autorizado para requisições não autenticadas
• 403 Proibido para requisições autenticadas, mas não autorizadas
• 404 Não encontrado para recursos inexistentes
• 500 Erro interno do Servidor para erros no servidor

Versione Sua API

Use versionamento na URI, isso permite que haja compatibilidade retroativa quando você introduz mudanças que não são retrocompatíveis.

A primeira versão disponível não precisa necessariamente ter o versionamento, mas se houver mudanças que inserem uma incompatibilidade dos consumidores existentes, a API deve ser versionada.

Exemplo:

/v1/.../usuarios.

Paginação e Filtragem

Para requisições GET que retornem uma lista, ofereça sempre o suporte à paginação.

Exemplo:

/usuarios?page=2&limite=50

Permite a filtragem de recursos.

Exemplo

/usuarios?status=pendente

Tratamento de Erros

Sempre retorne uma mensagem de erro significativa, com um código de erro único, para que os clientes possam entender e lidar com o erro adequadamente.

A mensagem de erro pode ser padronizada em um formato JSON, contendo um código de erro único e legível (mnemônico) e uma mensagem de erro amigável.

Suporte para Tipos de Mídia

Use o cabeçalho Accept para permitir que os clientes especifiquem o formato da resposta (por exemplo, JSON, XML) e o cabeçalho Content-Type para especificar o formato dos dados que estão enviando.

Use o tipo 'application/json' sempre que possível.

Segurança da API

Mecanismos comuns incluem tokens (por exemplo, JWT) ou chaves de API.

Forneca um Limite de Taxa

Defina um limite de quantas vezes os clientes podem fazer requisições.

Use ETags ou Cabeçalhos Last-Modified

Para cache e para lidar com requisições condicionais. Isso ajuda a reduzir a largura de banda e garantir a integridade dos dados.

Use Cabeçalhos de Link para Metadados de Paginação

Em vez de incluir metadados de paginação no corpo, use cabeçalhos de link. Isso pode apontar para next, prev, first e last páginas

Inclua uma Mensagem Auto-descritiva

As mensagens de retorno devem ser claras e objetivas expondo de fato o que causou o impedimento do processo

Registro e Monitoramento

Sempre registre requisições, respostas e erros. O monitoramento pode ajudar a detectar anomalias e problemas de desempenho

Documentação

Forneça documentação detalhada para cada endpoint, incluindo exemplos de requisições e respostas.

Mantenha a Idempotência

Garanta que as operações como PUT e DELETE sejam idempotentes, ou seja, evite fazer requisições desnecessárias garantindo a fluidez do processo.

Validação de entrada de dados

JSON Schema

Aplicação de regra de negócio

• Evitar se possível (na dúvida traga a questão para discutirmos).
• Regras de integração tudo bem (transformações, composições, adequações etc).

Transformação de dados

• Transformações para tornar as entidades mais aderentes aos padrões de APIs REST –> sim.
• Outras transformações a critério (traga para discussão).

Tratamento de exceptions

Em aplicações tradicionais, a orientação é fazer try/catch nas exceções se há intenção de tratá-las ou relançá-las para guardar alguma informação adicional no stack trace, e implementar um tratamento global.

O tratamento de exeptions para as rotas Camel já é feito por padrão no modelo do arquetipo que gera os microsserviços, sendo o ponto único de tratamento na classe BaseRoute.java, onde é feito o processamento da Exception e a geração da mensagem de resposta adequada.

Modelo de logging

O modelo é ser adotado pela aplicação é baseado em alguns princípios:

• Framework: Estamos adotando o framework Gelf. Existem várias bibliotecas disponíveis para todas as linguagens de programação atuais.
• Estratégia: O LOG deve ser incorporado a aplicação de maneira a fornecer recursos para acompanhamento da execução. Sempre que possível fazer a formação da MSG de LOG para que informações pertinentes ao processo sejam registradas (datas, métodos, sessions, retornos, etc).
• Boas práticas: Não devem ser registradas informações como senhas e tokens. O nível de LOG padrão deve ser sempre de INFO, para informações de acompanhamento, WARN para situações fora do comum e ERRO somente para casos em que o fluxo de execução foi totalmente interrompido. O nível DEBUG só deve ser usado no período de desenvolvimento e essas linhas devem ser removidas do código e não comentadas. Sempre que possível utilizar NDC.


Referência: https://go2docs.graylog.org/5-0/getting_in_log_data/gelf.html

Status code de retorno

Use padrão HTTP (em geral), para:

Requisições bem sucedidas

Retorno de erro do cliente

Retorno de erro do Integrador.SP.GOV.BR