REST API Snippets

A ideia é trazer um conteúdo mais rápido e direto sobre REST API's. Vou tentar trazer um problema real, e uma sugestão de solução abordando temas como design de api, governança e métricas!!!

Problema

Precisamos modelar um endpoint que vai fazer trazer informações de contratos.

Contrato da API

{
  "idContrato": 000,
  "nome": "",
  "cpf": "",
  "status": "",
  "saldoDevedor: ""
}

Endpoint GET

Vamos trabalhar com a obtenção dos dados de contrato, com algumas premissas:

• Um cliente pode ter vários contratos
• Proteger o backend de possíveis ataques para descobrir atualizações, ja que a regra de negócio nos permite atualizar esse status apenas uma vez por dia.

A primeira coisa a pensar é o design do endpoint, e aqui não tem muita coisa que inventar. Como estamos manipulando recursos (no plural) o ideal é que possamos utilizar /contratos como ponto de partida.

Agora a parte, que pouca gente se preocupa é que futuramente esse endpoint vai ser utilizado por outras soluções que precisam aplicar alguns filtros para trazer os dados. E aqui a dica é simples, use e abuse de query params.

Pensa que você precisa trazer todos os contratos inadimplentes, ou ainda, precisa de todos os contratos de um CPF específico. Para casos como esse (simples de certa forma), as boas práticas do REST, cobrem este ponto perfeitamente.

Exemplos:

• Lista todos os contratos do CPF em específico:

  • GET /contratos?cpf=0000000

• Lista contratos inadimplentes

  • GET /contratos?status="inadimplente"

• Contratos do CPF específico e que estejam adimplentes.

  • GET /contratos?cpf=00000&status="adimplente"

Parece besteira, mas com coisas assim habilitamos o negócio para construir os produtos sem reescrever tanto código.
Além da aceleração do negócio, conseguimos ganhar algumas coisas com implementações assim:

• Cache - Podemos habilitar o cache, por algum query param, e viabilizar o correto dimensionamento de recursos. Pensa que neste caso hipotético, o status muda 1 vez por dia, então pra que ir no backend sempre? Podemos utilizar o CPF como chave do cache nessa consulta e manter o TTL de 1 dia. Caso precise invalidar o cache antes, condicione esta rotina ao chamar um endpoint de atualização do status por exemplo...
• Aproveitamento de recursos - Com implementações assim, garantimos menos código para manter (imagina expor um endpoint pra busca por cada status, ou por cpf, ou ainda que combine duas coisas).

Conclusão

Existem outras tecnologias, que poderiam ser incorporadas para tornar a implementação mais flexível (OData, GraphQL), mas novas tecnologias precisam ter seu propósito bem definido para valer o custo de implementação dentro de nossos projetos. Com coisas simples, e com menos dor de cabeça é possível atingir o mesmo objetivo. Afinal, menos é mais!!