.png){kind=small}
.png){kind=small}
Este artigo trata de um tópico muito específico, mas de grande importância para o design de uma API: o design do seu retorno.
Uma API RESTFul é uma API que fornece interoperabilidade entre sistemas de computadores na internet utilizando as capacidades oferecidas pelo protocolo HTTP. Esta é uma definição simples e poderosa que guia as boas práticas de design de APIs corporativas.
No entanto, durante experiências práticas ao longo da carreira, por vezes vejo algumas discussões e desvios em relação a ações, princípios e definições do RESTFul. Isso acontece, muitas vezes, por uma governança de APIs mais frouxa ou pela forma de trabalho estabelecida entre os times.
Por isso, é importante trazer este tópico à baila para aumentar a maturidade sobre os conceitos e métodos relacionados ao RESTful e, com isso, ajudar a superar dificuldades encontradas ao integrar outras tecnologias.
São estes impactos que vamos explorar neste artigo, onde tentaremos usar exemplos práticos, mas evitando o trivial.
Algumas vezes, os desenvolvedores de APIs estão preocupados apenas com requisitos funcionais imediatos e pouco com o ecossistema em si e talvez minimizem os impactos dos padrões, algumas vezes até recriam padrões que já estão definidos.
Os padrões são criados para facilitar o reuso, são aplicados para resolver um problema recorrente. O RESTFul é um exemplo, por definir um estilo de arquitetura baseado em padrões e especificações já existentes. Isso agiliza a comunicação e interação de toda a comunidade em torno das APIs.
No caso, o próprio protocolo HTTP define o conjunto de status code. Uma definição do status code no design de uma API que não esteja em conformidade com o protocolo, além de depreciar a experiência de quem as consome, dificulta o monitoramento e a própria interoperabilidade dos sistemas.
Um exemplo prático, é quando o backend fornece um webservice SOAP, em que todos os retornos são 200 com o erro no body. É altamente recomendável a tradução desse retorno no API Gateway, mas nem sempre é viável. Pode ser o caso de um webservice do SAP que pode retornar mais de 40 mil códigos de erros diferentes, tornando o trabalho muito difícil ou talvez inviável. Ainda assim, neste cenário é importante pelo menos tentar separar o sucesso, de erro de cliente e de erros de servidor. Erros de servidor geralmente demandam uma ação mais imediata para restaurar ou melhorar a disponibilidade dos serviços, enquanto erros de cliente uma análise mais analítica com objetivo de melhorar a experiência dos usuários e parceiros.
Outro exemplo é quando a API não encontra um recurso específico e se define o status code 404-Not Found como retorno da chamada. A razão disso é que o cliente solicitou um recurso, com um identificador que não existe. Logo faz sentido que seja indicado ao cliente um erro na sua solicitação. Algo como, “olha, você errou na chamada, pois o recurso com o identificador que você pediu não existe”.
Por outro lado, se a chamada é direcionada à coleção de recursos com um filtro que não contempla nenhum recurso da coleção, isso não é um erro, já que a coleção existe e há recursos dentro da coleção, o status code 404 não é adequado. Este é um caso de sucesso em relação a chamada em si, então faz sentido retornar 200 caso se deseje retornar alguma mensagem além do status de sucesso ao cliente ou 204 caso não precise retornar qualquer conteúdo.
Retornar a classe errada nas chamadas, misturando sucesso, erros do cliente e erros do servidor, sem dúvida, já é um problema crítico que prejudica o DX (Developer Experience) e reduz as chances de reúso. Mas o problema não é só esse. Não devemos pensar que a API está conectada apenas a algumas aplicações frontend e backend. Na prática, haverá Firewalls, CDN, APM e outras ferramentas conectadas à API, ainda que de modo transparente para o desenvolvedor. E mesmo que esta API seja para uma integração ponto-a-ponto.
Indicar um erro com o código inadequado irá induzir o tratamento equivocado em todas as ferramentas do ecossistema corporativo, bem como alguns frameworks podem não funcionar adequadamente e precisar de adaptações.
Ferramentas que automatizam alertas, tal como o Sensedia Flexible Action ou outra ação baseada nestes retornos, serão impactadas. Assim como dashboards de monitoramento terão seus quadros e indicadores distorcidos.
Para concluir, vimos a importância de tratar corretamente o retorno das APIs, mas também há outros aspectos no design da API tão relevantes quanto para o ecossistema de serviços e aplicações de uma organização. Primeiramente, as equipes devem estar bem treinadas e as referências bem documentadas, atualizadas e de fácil acesso e entendimento. Também é importante contar com especialistas que possam esclarecer detalhes das especificações e padrões ou ajudar nos casos mais complexos.
Neste sentido, além de ferramentas como API Platform, Adaptive Governance e Flexible Action que a ajudam a expor boas APIs, a Sensedia oferece uma gama de serviços de consultoria pronta a ajudar a fazer melhor uso das APIs e a garantir o sucesso da estratégia de API. Clique aqui e confira nosso site.
