Saiba a importância do padrão de retorno de uma API

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 tempos.

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.

A importância do status code correto

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 como consome, dificulta o monitoramento e a própria interoperabilidade dos sistemas.

Exemplos práticos

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 Gatewaymas 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 exigem 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-Não encontrado como retorno da chamada. A razão disso é que o cliente solicitou um recurso, com um identificador que não existe. O logotipo 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.

A importância de identificar o status code correto

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 como 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 front-end 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 algumas estruturas não podem 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 os painéis 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 Plataforma API, Governança Adaptativa e Ação Flexível que a ajudam a exportar 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 o nosso site.

‍