Ausência de padrão em APIs: como prevenir bugs com a padronização
Eu e minha amiga Dani Cavalcanti decidimos escrever este artigo a fim de compartilhar um pouco da nossa vivência trabalhando com qualidade e testes em APIs, levando em consideração que o foco aqui é falar da atuação de um QA ágil e, a preocupação maior é a prevenção de bugs ao invés de encontrá-los durante o desenvolvimento projeto. O problema em questão é ausência dos padrões de API Rest desde o início do projeto o que acarreta em refatorações de código e problemas no momento que ocorrem as integrações.
Considerando que trabalhamos com microsserviços e APIS, temos entregas constantes de desenvolvedores diferentes, cada um atuando em um determinado contrato de API. Com isso, o que pode acontecer, é cada desenvolvedor estar fazendo à sua maneira, considerando esta a mais correta o que pode nos levar ao problema da falta de padrão que vamos explicar a seguir:
Status Codes associados aos métodos
O status code 200 (OK) é um retorno de sucesso e que pode estar associado ao método GET, PUT, PATCH ou DELETE. Já para um POST, estamos criando um objeto e inserindo na base, então, deveríamos retornar status 201 (Created).
Temos o caso também dos status 400 e 404.
● O status 400 (Bad Request) é utilizado quando, por exemplo, for inserida uma informação que a API não estava esperando. Podemos dar o exemplo de um campo int receber uma string. Nesse caso, ser retornado status code 400.
● O caso de 404 (Not Found), podemos dar o exemplo de quando passamos um id e este não existe na base de dados.
Sabe-se que cada desenvolvedor pode ter o seu entendimento, ou não, a respeito dos status code que serão retornados para cada caso e isso pode gerar a falta de padrão de status code e futuramente gerar a refatoração do código.
Vamos imaginar que temos o cenário de APIs que retornam status 400 quando id não encontrado na base e outros retornando 404. Em alguns casos, ainda podemos encontrar retorno de status 500.
Quando não se tem um documento a ser seguido, algo que seja padronizado com relação a status code e mensagens de retorno, a tendência é encontrar muitos problemas no futuro durante o projeto.
E como o QA deve atuar nesse processo?
Considerando a prevenção de bugs e refatorações indesejadas, antes de ser iniciado o projeto, dependendo de como as equipes se estruturam dentro da organização, o time de QA deve se reunir com o cliente e/ou arquitetos para a definição da padronização de status code e posteriormente elaboração de uma documentação que venham descritas as definições de padronização de status code, qual será utilizado para cada situação e com a mensagem que a API retornará.
Observação: A mensagem personalizada que a API vai retornar não precisa necessariamente estar nesse documento, pois cada mensagem vai depender de determinado fluxo, então as mensagens podem estar descritas nas estórias de usuário que serão definidas ao longo do projeto. Por exemplo, status code 400 com a mensagem “ CPF inválido”.
Vale ressaltar que durante o desenvolvimento, o QA deve olhar o código (realizar o teste estático) a fim de verificar os status code de cada método e se estão dentro dos padrões que foram definidos. Se o QA estiver confortável, ele pode e deve fazer alterações caso encontre algum erro. Esse processo auxilia muito o desenvolvimento, dá mais autonomia ao QA e facilita a vida dos desenvolvedores.
Uso do Problem Detail
Para tratar das mensagens de erros em nossas aplicações, Natália e eu sugerimos aos nossos desenvolvedores que usassem o Problem Detail.
A especificação RFC 7807 — Problem Details for HTTP APIs, criada em março de 2016 pela IETF, foi criada com o intuito de padronizar os formatos de mensagens de erro em APIs HTTP, evitando assim que novos formatos sejam criados.
A especificação basicamente trata das mensagens de erro dos status code entre os ranges 400 e 500. Além disso usa-se no header Content-Type o tipo aplication/problem, incluindo o formato da serialização da mensagem, json ou xml.
Com isso, caso o contrato de API retornasse algum status code entre os ranges 400 e 500, no body response da requisição viria um retorno com as seguintes informações:
● Type (string): Identifica o tipo de problema. Esta especificação gera uma documentação legível para o tipo de problema.
● Title (string): Contém um breve resumo do tipo de problema. Não deve mudar de ocorrência do mesmo tipo a não ser para fins de localização.
● Status (inteiro): O código de status HTTP gerado pelo servidor de origem para a ocorrência desse problema.
● Detail (string): uma explicação legível específica para esta ocorrência do problema.
● Instance (string): Uma referência de URI que identifica a ocorrência específica do problema. Pode ou não fornecer mais informações se não for referenciado.
Tendo isso em mente, foi criada na arquitetura do projeto uma estrutura, para que se desenvolvesse o código baseando-se nessa especificação.
Uso do Produces Response Type
Também sugerimos que para as mensagens de status code do range 200, o uso do Produces Response Type. Criamos no projeto de API, uma pasta que chamamos “Base” e dentro dela uma classe onde descrevemos cada mensagem que deveria ser retornada para o status code retornado. Por exemplo:
● GET (200) — “Consultado com sucesso.”
● PUT (200) — “Alterado com sucesso.”
● DELETE (200) — “Excluído com sucesso.”
● POST (201) — “Criado com sucesso.”
Concluímos que, após aplicar as técnicas e padrões descritos acima, foi possível garantir que todos os contratos de API tivessem as mesmas mensagens de retorno de status code, sanando assim o problema de falta de padronização fazendo com que pudéssemos atingir uma maior qualidade tanto nas APIs quanto no projeto como um todo.
