REGISTRO DOI: 10.69849/revistaft/cs10202512212329
Ivana Batista Marinho
Orientador: Francisco Abud Nascimento
Resumo
O presente artigo objetiva apresentar boas práticas no desenvolvimento de APIs (Interface de Programação de Aplicações) com arquitetura REST (Representational State Transfer) e tem como foco a estrutura de endpoints semânticos utilizando corretamente os verbos HTTP, uma vez que, seu correto uso constitui um pilar do REST. Além disso, trata da nomenclatura limpa das URIs, que servem para definir o caminho nas requisições HTTP. Uma URI deve representar um substantivo, já que é um recurso e como tal possui características e comportamentos. Este estudo também explica as camadas clássicas e mínimas para sua efetiva comunicação de forma que se obtenha alta coesão e baixo acoplamento. Por fim, trata das validações necessárias para evitar que campos nulos ou inválidos sejam tratados logo ao serem recebidos, de forma a se evitar que esses dados se propaguem por todo o código e só sejam identificados como inválidos no momento da consulta. Todo o estudo foi desenvolvido com base em livros teóricos de estudiosos do tema.
Palavras-chave: REST. Boas práticas. Api. HTTP.
1. INTRODUÇÃO
Uma API pode ser definida como um conjunto de funcionalidades que servem para acessar um software ou até mesmo outra API. É um sistema intermediário, uma ponte de acesso que facilita a comunicação entre aplicações. Isso claramente se vê no significado de seu acrônimo: Interface de Programação de Aplicações – ou seja, é o software que intermedeia aplicações.
De acordo com Zimmermann et al. (2025, p. 8), as APIs têm a natureza mútua de conectar e separar. Esse paradoxo se explica pois à medida que servem para conectar aplicações, servem para separar as funcionalidades que serão disponibilizadas para o consumidor dessa API, utilizando-se de um processo de abstração.
O autor cita a importância das APIs na atualidade:
As APIs hoje lidam com publicidade, bancos, computação em nuvem, diretórios, entretenimento, finanças, governo, saúde, seguros, empregos, logística, mensagens, notícias, dados abertos, pagamentos, QR codes, imóveis, redes sociais, viagens, encurtamento de URI, visualização, previsão do tempo e códigos postais. (ZIMMERMANN et al., 2024, p. 8).
As APIs estão em todo o lugar e em praticamente todas as áreas. Qualquer sistema online dificilmente não terá uma API para expor funcionalidades na web. Esse caráter quase onipresente das APIs acende uma luz sobre a necessidade de que sua implementação seja feita para permitir sua manutenibilidade, consistência, facilidade de uso e performance. Por esse motivo, o presente estudo se debruça sobre as boas práticas para garantir esses objetivos.
Boas práticas são convenções, padrões cuja finalidade é tornar o código mais legível, eficiente e de boa manutenibilidade, atendendo ao objetivo primário da Engenharia de Software: desenvolver software de qualidade.
Para implementação de APIs, existem alguns padrões arquiteturais usados e o foco deste artigo é o REST (Representational State Transfer), que significa Transferência de Estado Representacional, que é basicamente a forma de desenvolvimento da API utilizando o protocolo HTTP na comunicação. BARRETO (2023) afirma que REST é um estilo de arquitetura que define um conjunto de princípios e restrições para o desenvolvimento de APIs. Ele utiliza o protocolo HTTP como base para a comunicação entre cliente e servidor.
Tendo como foco a arquitetura REST, dentro do cenário de boas práticas, a sua implementação exige endpoints escritos de forma semântica com a utilização correta os verbos HTTP, a definição precisa da nomenclatura dos recursos expostos na URI, bem como a utilização de camadas separadas por suas respectivas responsabilidades, além de uma efetiva validação de seus campos para prevenir problemas como NullPointerException.
Nesse sentido, para alcançar o objetivo de analisar as convenções de boa escrita de código, esse artigo pretende se valer de livros escritos por estudiosos da área para expor o que vem sendo aceito e desenvolvido no decorrer do tempo.
2. FUNDAMENTAÇÃO TEÓRICA OU REVISÃO DA LITERATURA
2.1 USO ADEQUADO DOS VERBOS HTTP
Controller é a camada da aplicação responsável por receber as requisições e enviá-las para o método respectivo contido no service, camada que processa os dados de acordo com a regra de negócio. O controller é formado por um ou mais endpoints. De acordo com Torres (2021), endpoint é o endereço (URL) do ponto de entrada de um serviço, ou seja, a localização em que a API acessa os recursos necessários.
Cada endpoint deve conter a anotação respectiva de cada verbo HTTP seguida do caminho necessário para acessar o recurso. Assim, caso seja feita uma requisição para inserir dados, o verbo correto é o POST, conforme BARRETO (2023), o verbo POST é usado para criar um recurso no servidor. É uma operação que pode ter efeitos colaterais, como a criação de um novo registro no banco de dados.
Em conformidade com o explicado pelo autor, o verbo POST é usado quando se quer alterar o estado do servidor, de forma a adicionar um novo recurso. Quando se fala em mudar o estado do servidor, é importante saber que se está falando sobre ações que visam adicionar, remover ou alterar qualquer dado gerenciado pelo servidor. Os seguintes verbos fazem isso: PUT, PATCH, DELETE e POST. Esses são os verbos mais usados no desenvolvimento.
Já o verbo GET é usado para consultar informações do servidor. BARRETO (2023) afirma que o verbo GET é usado para recuperar dados de um recurso específico. É uma operação segura e não deve ter efeitos colaterais no servidor.
O efeito colateral se trata da idempotência, propriedade que os verbos possuem de poder ser chamados mais de uma vez sem alterar o estado do servidor.
Quando se fala em alterar um recurso, dois verbos HTTP aparecem: PUT e PATCH. Para substituir um recurso por outro, usa-se o PUT e para alterar alguns atributos do recurso, o mais indicado é o PATCH.
Ainda existe a possibilidade de excluir um recurso e para isso, o verbo indicado é o DELETE.
É importante salientar que, não se deve usar o verbo POST para recuperar, deletar ou alterar algum recurso, sob pena de desvirtuar a finalidade desse verbo e comprometer a legibilidade do código.
2.2 NOMENCLATURA DOS RECURSOS
Cada endpoint, além de conter o verbo HTTP relacionado com o que se pretende fazer no servidor (inserir, recuperar, alterar ou deletar), ele também deve conter uma URI que especifica o caminho para o recurso.
O recurso pode ser definido como um dado que vai ser disponibilizado na web. Esse dado pode ser qualquer coisa, como uma nota fiscal, um livro, uma tv, uma caneta etc. Esses recursos são identificados por URIs (Uniform Resource Identifier), em tradução: Identificador de Recurso Uniforme, que pode ser entendido como uma cadeia de caracteres com a finalidade de prover um endereço único ao recurso.
Dessa forma, a URI deve referenciar um substantivo. Não é uma boa prática usar verbos para identificar um recurso, já que, como visto, o recurso é um tipo de objeto e como tal possui propriedades e características. Verbos representam ação cuja indicação já está devidamente definida no verbo HTTP.
Nesse sentido, preconiza Nicholas:
“The first step in designing endpoints is ensuring they are resource-oriented. This means that endpoints should represent nouns, not verbs, because the action is expressed through the HTTP method. For example, to work with users in a system, the resource should be represented as /users. If a specific user is needed, the endpoint becomes /users/{id}, such as /users/25. By sticking to nouns, the API stays consistent with the principle that URIs represent resources.”. NICHOLAS (2025, p. 29).
As ações já são representadas pelos verbos HTTP. Não é uma boa prática criar um endpoint cuja URI seja um verbo, por exemplo: “/adicionar”. O POST já indica que aquele endpoint é para inserir um dado. A redundância quebra a legibilidade.
Nesse sentido, para a criação de um novo usuário, o ideal seria fazer um POST /usuarios.
Caso seja uma consulta, por exemplo, o verbo HTTP GET já indica que se está buscando recuperar um recurso do servidor, não é necessário indicar na URI um “/consultar”. Isso faz com que a anotação do verbo GET seja repetitiva, uma vez que já se indicou que se quer obter um recurso.
Assim, para consultar todos os usuários, é suficiente fazer GET /usuarios. Esse raciocínio se aplica aos demais verbos. Quando se deseja substituir o recurso completamente: PUT /usuarios/1 ou caso se queira atualizar um recurso parcialmente: PATCH /usuarios/1.
Da mesma forma para remover o usuário 1: DELETE /usuarios/1.
Ao se aplicar essas regras, o endpoint fica mais limpo e com melhor legibilidade.
2.3 CÓDIGOS DE STATUS SEMÂNTICOS
Cada resposta deve ter um código de status que informa o resultado da operação. Esse código é padronizado e possui 3 dígitos.
De acordo com MASSE (2012), REST APIs use the Status-Line part of an HTTP response message to inform clients of their request’s overarching result.
Esses códigos de status são divididos em 5 categorias informativas:
1xx – Informação. Indica que a requisição foi recebida e que está em processamento.
2xx – Sucesso. Indique que a requisição foi recebida, processada e concluída com sucesso.
3xx – Redirecionamento. Indica a necessidade de execução de uma ação por parte do cliente para finalizar a requisição.
4xx – Erro do Cliente. Indica que houve algum problema na requisição enviada pelo cliente.
5xx – Erro no Servidor. Indica que houve mau funcionamento no processamento por parte do servidor.
É importante que cada código de status seja devolvido conforme a situação respectiva. Isso facilita a leitura da resposta pelos programadores ou até mesmo a tomada de decisão por parte do cliente.
Não é uma boa prática devolver o código 200 para tudo. Assim, caso se faça uma requisição para inserir um novo usuário e o processamento seja efetuado com sucesso, deve se retornar o código 201, que indica que o recurso foi criado corretamente. Da mesma forma, no caso de remover um recurso do servidor, o código de resposta mais indicado é o 204, que indica que a operação foi realizada, mas não é devolvido um corpo na resposta.
2.4 RESPONSABILIDADES DEFINIDAS
A arquitetura REST possui algumas camadas bem definidas, as mais comuns são: Controller, Service e Repository. A camada de Controller, como explicado anteriormente, é a camada responsável por receber as requisições. Cada método deve ser limpo e se ater somente ao recebimento da requisição e devolução da resposta.
Já a camada de service é a responsável por fazer o processamento e orquestrar as chamadas ao Repository ou outros serviços. Essa camada deve ter métodos coesos, legíveis e deve conter qualquer regra relacionada ao negócio. Nele são implementadas as operações principais. Assim, em um cenário de cadastro de um novo usuário, a verificação de que o email já existe deve ser feita no service.
E a camada de Repository é aquela que faz a comunicação com o banco de dados. O controller recebe a requisição de cadastro, o service verifica se o e-mail do cliente já existe, se não, insere no banco de dados um novo registro, caso exista, deve retornar uma mensagem informando que o usuário está cadastrado.
2.5 VALIDAÇÕES
Validar os dados é muito importante. Não é uma boa prática receber um dado sem passar por tratamento algum. Muitas vezes um dado que não poderia ser nulo é recebido como nulo e ele vai se propagando por todo o código até o momento da consulta. Quanto antes se verificar que um dado não atende requisitos obrigatórios, melhor.
De acordo com Barreto (2023, p. 44):
A validação de dados consiste em verificar se os dados inseridos ou recebidos pela API atende às regras e restrições definidas no esquema. Isso inclui a verificação de tipos de dados, formatos, faixas de valores permitidos, obrigatoriedade de campos, entre outros. A validação de dados pode ser feita tanto no lado do cliente, antes de enviar os dados para a API, quanto no lado do servidor, ao receber e processar os dados.
Cada validação vai obedecer a regras específicas, por exemplo: verificar se um CPF tem 11 caracteres e que eles são apenas números, verificar se um endereço de e-mail é válido, entre outras.
Essas validações devem ser feitas o quanto antes para evitar que o dado vá se propagando pelo código sem necessidade alguma, já que é inválido.
Barreto (2023, p. 44) diz:
Ao realizar a validação de dados, é importante tratar adequadamente os erros que podem ocorrer. Em caso de dados inválidos, a API deve retornar mensagens de erro claras e informativas, indicando qual campo ou regra de validação foi violado. Isso ajuda os clientes da API a corrigirem os dados e a evitar erros futuros.
No caso de um cadastro de usuário, é necessário verificar se o CPF inserido é válido e caso não seja, deve ser retornada uma mensagem de erro informando que o dado é inválido.
As mensagens devem ser claras, objetivas e explicar especificamente qual o dado problemático para que o consumidor da API possa corrigir e enviar uma nova requisição.
3. METODOLOGIA
O presente artigo se identifica como uma revisão sistemática da literatura composta por livros de autores brasileiros e estrangeiros que tratam do desenvolvimento de software com foco na exposição de boas práticas aplicadas na programação.
A escolha da bibliografia passou por três etapas: Pesquisa, Seleção e Análise.
1. A pesquisa foi feita do dia 01 ao dia 10 de setembro do ano de 2025. As plataformas utilizadas foram o Google e ChatGPT. Os termos utilizados na pesquisa foram: Livros de Boas Práticas para APIs RESTful e Livros que tratam de Desenvolvimentos de APIS com qualidade.
2. A seleção se deu mediante leitura online de trechos do livro e de avaliações na Amazon brasileira de consumidores que adquiriram o produto. Levando em conta, nessas avaliações, notas acima de 4 estrelas, sendo 5 o máximo. Também foi solicitado ao ChatGPT um resumo de alguns desses livros explanando quais as ideias centrais que envolviam as boas práticas no desenvolvimento. A escolha se deu mediante pertinência do assunto com o tema do artigo.
3. Na fase de análise, os livros foram adquiridos, tanto em formato físico, quanto em formato digital. Os trechos que enfatizam as boas práticas foram selecionados e categorizados conforme sua pertinência temática.
4. CONCLUSÃO
Ao analisar os textos dos estudiosos sobre desenvolvimento de software utilizando boas práticas, reafirma-se o caráter substancial de um software de qualidade com consistência, manutenibilidade e performance. Essa padronização ajuda um novo desenvolvedor a entender melhor o código, reduzindo a curva de aprendizado, de forma que sua manutenção seja feita com mais agilidade.
Quando se fala em endpoints semânticos, também existe a pretensão de que uma pessoa que não seja familiarizada com código entenda o que ele faz. É como se fosse uma linguagem universal, uma estrutura intuitiva de fácil interpretação para qualquer pessoa.
No quesito de validação, o objetivo é verificar de pronto se aquele valor enviado é válido naquela situação, de forma que se evite o erro no momento da persistência no banco de dados. O ideal é que os campos sejam validados o mais rápido possível e com retorno de mensagem específica para que o cliente entenda que o valor enviado é inválido e tome uma decisão.
A separação em camadas ajuda na organização do código, de forma que as regras de negócio se concentrem em uma camada própria de forma isolada. Isso ajuda na manutenção do software, procura de bugs e correção de erros.
As boas práticas só trazem benefícios ao projeto. Ajudam na manutenibilidade, diminuem a curva de aprendizado de novos desenvolvedores, diminuem a possibilidade da ocorrência de erros e consequentemente melhoram a performance da aplicação.
REFERÊNCIAS
ZIMMERMANN, Olaf; STOCKER, Mirko; LÜBKE, Daniel; ZDUN, Uwe; PAUTASSO, Cesare. Padrões para design de API: simplificando a integração com troca de mensagens de baixo acoplamento. Tradução de Eveline Vieira Machado. Porto Alegre: Bookman, 2024.
BARRETO, João Victor. Manual de Boas Práticas para o Desenvolvimento de APIs. 2023. E-book (Kindle).
TORRES, Fernando Esquírio. Desenvolvimento de API REST (Série Universitária). 2021. E-book (Kindle).
NICHOLAS, Willie. Mastering Web API Design: Build Secure, Scalable, and Developer Friendly APIs with REST, GraphQL, and gRPC. 2025. E-book (Kindle).
MASSE, Mark. REST API Design Rulebook: Designing Consistent RESTful Web Service Interfaces. O’Reilly Media. 2012. Edição do Kindle.