Bruno Meneses do Nascimento; Jorge Carlos Valverde Rebaza

DOI: 10.22167/2675-6528-202600617

Artigo elaborado pela ferramenta ResumeAI, solução de inteligência artificial desenvolvida pelo Instituto Pecege voltada à síntese e redação.

Resumo

A crescente adoção de arquiteturas distribuídas intensificou o uso de Application Programming Interfaces (APIs) como principal mecanismo de integração entre sistemas backend. Em ambientes corporativos orientados a microsserviços, a proliferação de APIs ampliou desafios de consistência de contratos, evolução de interfaces, manutenção, segurança e integração entre equipes. Nesse contexto, a governança de APIs emergiu como elemento estratégico para padronizar o desenvolvimento, estabelecer regras de versionamento, documentação, segurança e reuso, visando reduzir redundâncias e inconsistências. O estudo objetivou desenvolver e avaliar um modelo estruturado de governança para APIs RESTful aplicado a sistemas backend. Adotou-se uma metodologia de pesquisa aplicada, de natureza experimental e abordagem quantitativa comparativa, baseada na implementação de duas versões equivalentes de uma API: uma sem padronização formal e outra construída com diretrizes estruturadas de governança. O modelo proposto incluiu versionamento explícito, padronização de respostas JSON, tratamento centralizado de erros, organização em camadas, documentação por OpenAPI e definição mínima de cobertura de testes. Analisaram-se métricas como complexidade ciclomática, duplicação de código, cobertura de testes, consistência contratual e tempo médio de implementação de endpoints. Os resultados evidenciaram redução da complexidade estrutural, menor duplicação de código, maior previsibilidade no desenvolvimento, e melhoria na consistência das respostas e facilidade de evolução do sistema. Concluiu-se que a adoção de um modelo estruturado de governança contribui positivamente para a qualidade arquitetural, a redução do débito técnico e a sustentabilidade de APIs RESTful em contextos backend corporativos.

Palavras-chave: arquitetura REST; backend; débito técnico; microsserviços; qualidade de software.

1. Introdução

A transformação digital impulsionou a demanda por integração entre sistemas e serviços distribuídos. As Application Programming Interfaces (APIs) tornaram-se o principal mecanismo de comunicação, essenciais para a interoperabilidade, reutilização de funcionalidades e expansão de ecossistemas digitais, sendo reconhecidas como fundamentais na arquitetura de software contemporânea e estratégia tecnológica (GARIMILLA, 2024).

O estilo arquitetural REST consolidou-se como padrão dominante para serviços web devido à sua simplicidade e aderência ao protocolo HTTP. A popularização de microsserviços reforçou a centralidade das APIs, transformando sistemas em serviços menores e independentes, que se comunicam por contratos. Essa abordagem oferece benefícios como escalabilidade e flexibilidade, mas aumenta a dependência de APIs consistentes, bem documentadas e estáveis.

Contudo, a proliferação de APIs em ambientes corporativos gera desafios significativos. A manutenção da uniformidade no design, nomenclatura, documentação, versionamento, códigos de erro e políticas de segurança torna-se complexa. A evolução constante das APIs, impulsionada por novos requisitos e ajustes, pode impactar consumidores na ausência de diretrizes claras para compatibilidade e gestão do ciclo de vida.

Estudos em microsserviços identificam problemas recorrentes na evolução de APIs, como análise de impacto de mudanças, comunicação ineficaz e degradação do design. Isso indica que a evolução técnica das APIs não é apenas implementação, mas também coordenação organizacional e definição de regras compartilhadas. A ausência de mecanismos formais que garantam consistência e previsibilidade na criação e evolução das APIs representa uma lacuna prática.

Nesse cenário, a governança de APIs emerge como elemento estratégico. Ela compreende o conjunto de padrões, políticas e práticas que orientam o desenvolvimento, publicação, documentação, proteção, versionamento e reuso de APIs. Seu objetivo é criar um ambiente para APIs mais fáceis de encontrar, seguras, escaláveis, reutilizáveis e alinhadas à estratégia de negócio. A governança contribui para mitigar a proliferação desordenada, reduzir redundâncias e reforçar conformidade técnica e regulatória.

A literatura sobre governança de APIs em larga escala destaca a combinação de regras padronizadas, documentação centralizada e automação de verificações. Um estudo industrial demonstrou que uma abordagem multifacetada gerou percepção positiva sobre o impacto da governança na qualidade, consistência e previsibilidade das interfaces. Isso reforça que a governança atua como suporte ao design e prevenção de falhas estruturais desde as fases iniciais do desenvolvimento.

Do ponto de vista da qualidade de software, a ausência de padrões de projeto e contratos consistentes para APIs pode levar ao acúmulo de débito técnico, aumento do retrabalho e custos de manutenção. Em arquiteturas distribuídas, esse efeito é amplificado pela interdependência entre serviços, afetando atributos como manutenibilidade, testabilidade, confiabilidade e modularidade. A consistência no design e a previsibilidade das respostas são cruciais para a adoção e integração.

Apesar da argumentação teórica em favor da governança, a literatura carece de avaliações quantitativas comparativas sobre seu impacto direto em métricas técnicas de qualidade de software, com foco em estudos conceituais, e não em validações práticas. Essa lacuna justifica a realização de estudos aplicados que comparem cenários com e sem governança formal para APIs RESTful em implementações backend reais. Diante disso, este trabalho tem como objetivo desenvolver e avaliar um modelo estruturado de governança para APIs RESTful em sistemas backend, analisando seus impactos por meio de métricas quantitativas de qualidade de software e de observações qualitativas relacionadas à consistência, manutenção e previsibilidade do desenvolvimento.

2. Material e Métodos

O presente estudo caracterizou-se como uma pesquisa aplicada de natureza experimental, com abordagem quantitativa comparativa. A metodologia adotada consistiu no desenvolvimento de duas versões equivalentes de uma Application Programming Interface (API) backend, focada no gerenciamento de usuários, para comparação direta entre um cenário sem governança formal e outro baseado em um modelo estruturado de governança. Implementaram-se cinco endpoints funcionais idênticos para operações CRUD básicas: criação (POST), consulta por identificador (GET), listagem (GET), atualização (PUT) e remoção (DELETE). A equivalência funcional foi assegurada pelos mesmos requisitos de entrada, regras de negócio e estrutura de dados.

Ambas as versões da API foram desenvolvidas pelo mesmo programador, de forma sequencial, iniciando-se pela implementação sem governança e, posteriormente, pela versão com governança. Esta abordagem visou mitigar potenciais variações experimentais, embora se reconheça que a experiência adquirida na primeira fase pode ter influenciado a eficiência na construção da segunda.

A opção por uma abordagem experimental justificou-se pela necessidade de mensurar impactos técnicos diretos da introdução de práticas de padronização e controle. Buscou-se um ambiente controlado para observar os efeitos da governança em atributos mensuráveis da implementação, alinhando-se a estudos de engenharia de software que validam práticas e arquiteturas (FISCHER et al., 2024).

A primeira versão da API foi desenvolvida seguindo uma implementação convencional, baseada apenas nas práticas padrão do framework utilizado, sem diretrizes adicionais de padronização, versionamento explícito ou centralização de regras contratuais. Este cenário representou um contexto comum de desenvolvimento incremental de APIs em ambientes corporativos sem um modelo de governança estabelecido.

A segunda versão foi construída com base em um modelo estruturado de governança, elaborado a partir de recomendações da literatura. Este modelo incorporou versionamento explícito por URI, padronização de respostas em formato JSON, tratamento centralizado de erros, organização arquitetural em camadas, documentação automatizada por OpenAPI e definição de cobertura mínima de testes. Diretrizes de consistência, automação de verificações e clareza contratual também foram consideradas.

O ambiente tecnológico utilizado para o desenvolvimento das APIs consistiu em Node.js, com o framework NestJS, banco de dados PostgreSQL e containerização via Docker. Este conjunto de tecnologias foi selecionado devido à sua ampla utilização em sistemas backend modernos e à capacidade de replicar um cenário de desenvolvimento corporativo orientado a serviços.

Para a análise estática e verificação da qualidade do código, utilizou-se a ferramenta SonarQube, versão 10.4, configurada com o perfil de regras padrão “Sonar way”, para obtenção de métricas como complexidade ciclomática e duplicação de código. Os testes automatizados foram executados com a biblioteca Jest, versão 29.7, por meio do comando “npm run test –coverage”, e a cobertura de testes foi extraída diretamente do relatório gerado.

As métricas analisadas incluíram: complexidade ciclomática média por endpoint (número de caminhos independentes nas funções); índice de duplicação de código (razão percentual de linhas duplicadas); cobertura de testes (proporção de linhas executadas); e tempo médio de implementação (média aritmética do tempo registrado para cada endpoint, do início da codificação à conclusão funcional). A consistência contratual das respostas HTTP foi avaliada por um checklist de cinco critérios binários: uso consistente de códigos HTTP, estrutura padronizada de resposta JSON, padronização de mensagens de erro, versionamento explícito e consistência de nomenclatura de endpoints.

A coleta de dados ocorreu após a implementação completa das duas versões da API, garantindo sua equivalência funcional. Ambas as versões foram submetidas aos mesmos critérios e operações de análise para preservar a comparabilidade. A interpretação dos resultados combinou a leitura quantitativa das métricas com uma discussão qualitativa, focada na relação entre governança, consistência, manutenibilidade, reuso e sustentabilidade técnica das APIs. O escopo controlado do experimento forneceu evidências aplicadas sobre como diretrizes estruturadas podem influenciar atributos técnicos importantes na construção de APIs backend.

3. Resultados e Discussão

A análise comparativa entre as duas implementações de API, uma sem governança formal e outra com um modelo estruturado, revelou diferenças significativas nos indicadores de qualidade de software. De forma geral, os resultados obtidos sugerem que a aplicação de um modelo estruturado de governança pode influenciar positivamente a qualidade técnica de APIs RESTful em sistemas backend. A versão desenvolvida sem diretrizes explícitas de governança apresentou maior complexidade estrutural, maior variabilidade nas respostas, maior duplicação de código e menor previsibilidade no processo de evolução. Em contraste, a implementação baseada em regras explícitas de governança demonstrou maior consistência, melhor organização arquitetural e condições aprimoradas para manutenção, alinhando-se a estudos que destacam a contribuição da governança para a previsibilidade em sistemas distribuídos (AHMAD et al., 2024).

O modelo estruturado de governança de APIs proposto e aplicado neste estudo incorporou diversos componentes para padronizar o desenvolvimento. Incluiu diretrizes para o design de APIs, como versionamento explícito por URI, padronização de respostas em formato JSON e tratamento centralizado de erros. A organização arquitetural em camadas foi um pilar, juntamente com a documentação automatizada via OpenAPI e a definição de uma cobertura mínima de testes. Embora o modelo original contemple elementos como validação por linters e pipelines automatizados, o experimento focou nos componentes diretamente implementados para mensurar seus impactos.

No que tange à complexidade ciclomática, a implementação governada exibiu uma redução de 50% na média, passando de 18 para 9. Essa diminuição foi consistente em todos os cinco endpoints analisados: o endpoint POST/users reduziu de 20 para 10, GET/users/:id de 16 para 8, GET /users de 14 para 7, PUT/users/:id de 22 para 11 e DELETE/users/:id de 18 para 9. Esse resultado indica que a definição prévia de camadas, responsabilidades e padrões de tratamento de exceções contribuiu para reduzir acoplamentos desnecessários e decisões ad hoc no código. Uma menor complexidade ciclomática facilita a compreensão, manutenção e evolução do sistema, além de mitigar o risco de introdução de falhas futuras, conforme a literatura que associa a qualidade de APIs à clareza do design e à consistência das regras.

A duplicação de código também apresentou uma redução expressiva de 72% na versão governada, caindo de 11% para 3%. Essa melhoria é atribuída à centralização de comportamentos comuns, como a padronização de respostas e o tratamento de erros, o que favoreceu o reuso de componentes e a clara definição de responsabilidades entre as camadas de controller, service e repository. A diminuição da duplicação é um benefício crucial em ambientes corporativos com múltiplos times e alta frequência de mudanças, pois contribui para uma base de código mais sustentável e menos suscetível a divergências de implementação, reduzindo o débito técnico e os custos de manutenção a longo prazo.

A cobertura de testes demonstrou uma melhora significativa na implementação governada, aumentando em 73%, de 45% para 78%. Esse avanço pode ser interpretado como uma consequência direta da maior modularidade e da melhor separação de responsabilidades alcançadas com o modelo estruturado. Quando as regras arquiteturais são mais claras e os componentes mais coesos, torna-se mais simples construir testes automatizados e isolar comportamentos específicos. Em arquiteturas orientadas a serviços, uma alta cobertura de testes é particularmente relevante, pois falhas em contratos e integrações podem se propagar rapidamente entre consumidores e provedores, reforçando a confiança na implementação e a segurança evolutiva da API.

Outro aspecto crucial foi a melhoria substancial na consistência contratual, que aumentou em 137%, passando de 40% para 95% na versão governada. Essa métrica foi avaliada com base em cinco critérios: uso consistente de códigos HTTP, estrutura padronizada de resposta JSON, padronização de mensagens de erro, uso de versionamento explícito e consistência de nomenclatura de endpoints. A padronização das respostas HTTP, dos códigos de status e do formato de erros reduziu ambiguidades e tornou a interface mais previsível para os consumidores. Esse ganho vai além da legibilidade técnica, influenciando diretamente a experiência de integração, o esforço de manutenção de clientes e a facilidade de comunicação entre equipes, conforme destacado na literatura sobre design e governança de APIs.

Em relação ao tempo médio de implementação de novos endpoints, a versão governada mostrou um desempenho superior, com uma redução de 35%, passando de 42 minutos para 27 minutos. Essa otimização foi observada em todos os endpoints: POST/users (de 45 para 30 minutos), GET/users/:id (de 38 para 25 minutos), GET /users (de 40 para 26 minutos), PUT/users/:id (de 48 para 29 minutos) e DELETE/users/:id (de 39 para 25 minutos). Embora a adoção de governança possa, inicialmente, parecer adicionar esforço, o experimento indicou que a existência de padrões previamente definidos reduz o tempo gasto em decisões repetitivas e retrabalho. A equipe, ao seguir um modelo conhecido, aumenta a previsibilidade e acelera a entrega, confirmando que a governança, quando bem estruturada, funciona como mecanismo de apoio e orientação ao desenvolvimento desde o início.

A previsibilidade observada neste estudo, embora não mensurada como uma métrica independente, é uma inferência derivada da padronização estrutural, da consistência contratual e da redução do tempo de implementação. Os achados também dialogam com o problema da evolução de APIs em ambientes de microsserviços. A literatura aponta que mudanças em APIs podem gerar dificuldades de comunicação entre equipes, dependência prolongada de versões antigas e degradação do design na ausência de mecanismos adequados de coordenação. No experimento, a versão governada mostrou-se mais preparada para evolução, possuindo contratos mais uniformes, documentação mais clara e organização mais previsível, o que mitiga os efeitos negativos da evolução desordenada das interfaces.

Do ponto de vista qualitativo, a versão sem governança revelou uma maior dependência de escolhas locais e uma heterogeneidade acentuada na implementação. Isso foi evidente na forma como as respostas eram estruturadas, no tratamento de exceções e na distribuição de responsabilidades entre componentes. Em sistemas de pequena escala, essas diferenças podem ser administráveis; contudo, em contextos maiores, com múltiplos serviços e equipes distribuídas, tendem a se multiplicar, gerando dificuldades de manutenção, integração e rastreamento de mudanças. A governança atua precisamente para evitar esse crescimento desordenado, estabelecendo limites e referências comuns para o desenvolvimento.

Os resultados obtidos permitem relacionar a governança de APIs com atributos clássicos de qualidade de software. A redução da complexidade ciclomática e da duplicação de código reforça a manutenibilidade do sistema. O aumento da cobertura de testes e a previsibilidade dos contratos favorecem a testabilidade. A padronização estrutural e a clara separação de responsabilidades fortalecem a modularidade. Em conjunto, esses fatores contribuem para diminuir o débito técnico e aumentar a sustentabilidade da solução. Portanto, os achados do experimento não apenas reforçam benefícios já discutidos na literatura, mas também agregam evidência aplicada ao mostrar que um modelo estruturado de governança pode gerar impactos mensuráveis em uma implementação backend concreta.

É importante destacar que a melhoria observada não decorre de um único elemento isolado, mas da combinação entre práticas complementares. O versionamento explícito, a documentação automatizada, o tratamento padronizado de erros, a organização em camadas, a definição mínima de testes e as regras contratuais consistentes atuaram de forma conjunta. Esse resultado se alinha à visão contemporânea de governança em larga escala, segundo a qual a qualidade não é garantida apenas por um documento de boas práticas, mas por um ecossistema de regras, automação e processos de revisão que orientam e validam o design das APIs.

Limitações do Estudo

Este estudo apresenta algumas limitações que devem ser consideradas na interpretação dos resultados. O experimento foi conduzido em um ambiente controlado, com escopo reduzido e um número limitado de endpoints, o que pode influenciar a generalização dos resultados para sistemas de maior escala e complexidade. Além disso, a experiência adquirida pelo mesmo desenvolvedor durante a implementação da primeira versão pode ter influenciado parcialmente a eficiência na construção da segunda versão, introduzindo um viés de aprendizado que, embora minimizado, não foi completamente eliminado.

Adicionalmente, não foram considerados aspectos como desempenho, segurança e integração com múltiplos sistemas externos, que são fatores cruciais e podem impactar a eficácia da governança em cenários reais de produção. A ausência dessas análises mais amplas restringe a abrangência das conclusões, indicando a necessidade de investigações futuras que contemplem esses elementos para uma compreensão mais completa dos benefícios e desafios da governança de APIs em contextos corporativos.

Trabalhos Futuros

Para expandir a análise e mitigar as limitações identificadas, trabalhos futuros podem focar na aplicação do modelo de governança em ambientes corporativos reais, com múltiplos serviços e equipes distribuídas. Isso permitiria avaliar seu impacto em cenários de maior complexidade e escala, fornecendo evidências mais robustas sobre a generalização dos resultados. Recomenda-se também a integração de ferramentas automatizadas de validação, como linters específicos para APIs e pipelines de integração contínua, para verificar a conformidade com as diretrizes de governança de forma contínua e automatizada.

Adicionalmente, sugere-se a inclusão de métricas complementares na análise, como desempenho (latência, taxa de transferência), segurança (vulnerabilidades, conformidade com políticas), e a experiência do desenvolvedor (facilidade de uso, curva de aprendizado). A avaliação desses atributos adicionais pode fornecer uma visão mais holística dos benefícios da governança de APIs, contribuindo para uma compreensão mais aprofundada de como essas práticas afetam a qualidade geral do software e a produtividade das equipes em ambientes de desenvolvimento complexos e dinâmicos.

Em síntese, os resultados deste estudo demonstram que a adoção de um modelo estruturado de governança para APIs RESTful em sistemas backend impacta positivamente a qualidade arquitetural. A redução da complexidade ciclomática, a diminuição da duplicação de código, o aumento da cobertura de testes e a melhoria da consistência contratual, juntamente com a previsibilidade no desenvolvimento, são evidências claras de que a governança contribui para a redução do débito técnico e a sustentabilidade das APIs em contextos corporativos. Esses achados respondem ao objetivo do estudo ao avaliar os impactos de um modelo de governança por meio de métricas quantitativas e observações qualitativas, reforçando a importância de diretrizes formais para o desenvolvimento de interfaces.

4. Conclusão

O presente estudo objetivou desenvolver e avaliar um modelo estruturado de governança para APIs RESTful em sistemas backend. Verificou-se que a aplicação desse modelo resultou em melhorias significativas em métricas de qualidade de software. Observou-se uma redução expressiva na complexidade ciclomática e na duplicação de código, indicando um design mais limpo e manutenível. Adicionalmente, identificou-se um aumento substancial na cobertura de testes e na consistência contratual, o que reforça a robustez e a previsibilidade das interfaces. A implementação governada também demonstrou uma diminuição no tempo médio de desenvolvimento de novos endpoints, sugerindo maior eficiência e previsibilidade no processo. Esses achados evidenciam que a governança de APIs, ao incorporar práticas como versionamento explícito, padronização de respostas JSON, tratamento centralizado de erros, organização em camadas e documentação por OpenAPI, contribui diretamente para a qualidade arquitetural, a redução do débito técnico e a sustentabilidade de APIs em ambientes corporativos.

Contudo, o estudo apresenta limitações inerentes ao seu delineamento experimental, como o ambiente controlado, o escopo reduzido e o número limitado de endpoints, o que restringe a generalização dos resultados para sistemas de maior escala e complexidade. Não foram avaliados aspectos cruciais como desempenho, segurança e integração com múltiplos sistemas externos, nem se eliminou completamente um possível viés de aprendizado do desenvolvedor. Para expandir a compreensão, sugere-se que trabalhos futuros apliquem o modelo de governança em ambientes corporativos reais, integrando ferramentas automatizadas de validação e incluindo métricas complementares de desempenho, segurança e experiência do desenvolvedor. Tais investigações podem fornecer uma visão mais abrangente dos benefícios e desafios da governança de APIs em contextos de desenvolvimento complexos e dinâmicos.

Referências Bibliográficas

AHMAD, M.; GEEWAX, J. J.; MACVEAN, A.; KARGER, D.; MA, K.-L. API Governance at Scale. In: INTERNATIONAL CONFERENCE ON SOFTWARE ENGINEERING: SOFTWARE ENGINEERING IN PRACTICE, 46., 2024, Lisbon. Proceedings […]. New York: ACM, 2024.

FISCHER, S.; URBANKE, P.; RAMLER, R.; STEIDL, M.; FELDERER, M. An Overview of Microservice-Based Systems Used for Evaluation in Testing and Monitoring: A Systematic Mapping Study. In: ACM/IEEE INTERNATIONAL CONFERENCE ON AUTOMATION OF SOFTWARE TEST, 5., 2024, Lisbon. Proceedings […]. New York: ACM, 2024.

GARIMILLA, M. The Art of API Design: Best Practices for Modern Software Development. International Journal of Engineering and Technology Research, v. 9, n. 2, p. 229-239, 2024.

Artigo oriundo de Trabalho de Conclusão de Curso da Especialização em Engenharia de Software do MBA USP/Esalq

Para saber mais sobre o curso, clique aqui e acesse a plataforma MBX Academy