Web

▶️ Spring Web Starter

O Spring Web Starter é uma dependência do Spring Framework que facilita a criação de aplicativos web baseados em Java, oferecendo as configurações necessárias para configurar uma aplicação web de forma rápida e eficiente. Ele faz parte do Spring Boot, que visa simplificar o processo de desenvolvimento e configuração de aplicações, eliminando a necessidade de configuração manual extensa.

O Spring Web Starter inclui todas as dependências essenciais para criar uma aplicação web, como o Spring MVC, que é a arquitetura baseada no padrão Model-View-Controller (MVC), e o Tomcat, um servidor de aplicação embutido, permitindo que você crie e execute aplicações web diretamente no seu ambiente de desenvolvimento. Além disso, o starter suporta o desenvolvimento de APIs RESTful, usando o Spring WebFlux para a construção de sistemas reativos, caso necessário.

Em resumo, o Spring Web Starter proporciona uma maneira simples e eficiente de configurar um aplicativo web ou API RESTful no ecossistema Spring, permitindo que os desenvolvedores se concentrem mais na lógica do aplicativo e menos na configuração e infraestrutura.

REST

REST (Representational State Transfer) é um conjunto de princípios arquiteturais para projetar serviços de rede. Criado por Roy Fielding em sua dissertação de doutorado em 2000, REST é um estilo de arquitetura que usa o protocolo HTTP para transferir dados entre sistemas de forma simples e escalável. Ele não define uma linguagem específica, mas sim um conjunto de princípios que orientam como as interações entre cliente e servidor devem ocorrer. As principais características do REST incluem:

1. Sem estado: Cada requisição HTTP do cliente ao servidor deve conter todas as informações necessárias para entendê-la. O servidor não armazena nada sobre o estado do cliente entre as requisições.
2. Baseado em recursos: Em REST, tudo é considerado um recurso (por exemplo, usuários, produtos, etc.). Cada recurso é identificado por uma URL única.
3. Operações padrão: As operações são mapeadas para os métodos HTTP:

• GET: Para recuperar um recurso.
• POST: Para criar um novo recurso.
• PUT: Para atualizar um recurso existente.
• DELETE: Para excluir um recurso.

4. Representações de recursos: Quando um cliente solicita um recurso, o servidor retorna uma representação desse recurso (geralmente em JSON ou XML). O cliente pode então interagir com essas representações.
5. Desacoplamento de cliente e servidor: O cliente e o servidor são independentes, e a comunicação entre eles deve ser feita por meio de chamadas HTTP.

RESTful

RESTful é um termo usado para descrever serviços que seguem os princípios e as melhores práticas do REST. Ou seja, quando um serviço é considerado "RESTful", significa que ele foi projetado e implementado de acordo com as diretrizes do REST. Não existe uma definição oficial de "RESTful", mas o termo é geralmente usado para indicar que um serviço adere aos seguintes pontos:

1. Uso adequado dos métodos HTTP: O serviço deve usar os métodos HTTP de maneira semântica. Isso significa usar GET para leitura, POST para criação, PUT para atualização e DELETE para remoção.
2. URLs bem estruturadas: As URLs devem ser estruturadas de forma a representar claramente os recursos. Por exemplo, /clientes pode ser uma URL para uma coleção de clientes, e /clientes/{id} para acessar um cliente específico.
3. Sem estado: A comunicação entre cliente e servidor deve ser sem estado, ou seja, cada requisição deve ser autossuficiente.
4. Uso de representações: A troca de dados entre cliente e servidor deve ser feita usando representações dos recursos, com formatos como JSON ou XML.

REST x RESTful

Embora os termos REST e RESTful sejam frequentemente usados de forma intercambiável, há uma diferença sutil. REST é o estilo arquitetural definido por Roy Fielding, enquanto RESTful é a implementação prática de um serviço que segue essas diretrizes. Em outras palavras:

• REST é o conceito.
• RESTful é a aplicação desse conceito em um serviço web.

Um serviço RESTful implementa corretamente os princípios do REST, como o uso de métodos HTTP de forma semântica e a exposição de recursos através de URLs. Portanto, um serviço pode ser descrito como RESTful se seguir essas práticas, enquanto um serviço que apenas usa HTTP para transferir dados de maneira não estruturada pode ser descrito como "baseado em REST" ou "não RESTful".

Exemplo

Imaginando uma API para gerenciar uma lista de clientes, a estrutura RESTful poderia ser algo assim:

• GET /clientes: Recupera uma lista de todos os clientes.
• POST /clientes: Cria um novo cliente.
• GET /clientes/{id}: Recupera as informações de um cliente específico.
• PUT /clientes/{id}: Atualiza os dados de um cliente específico.
• DELETE /clientes/{id}: Exclui um cliente específico.

Cada URL mapeia para um recurso, e as operações são realizadas por meio dos métodos HTTP apropriados. Isso é o que torna a API RESTful.

Nível de Maturidade

Para padronizar e facilitar o desenvolvimento de APIs REST, Leonard Richardson propôs um modelo de maturidade para esse tipo de API, definido em 4 níveis.

Nível 0: Ausência de Regras

Esse é considerado o nível mais básico de uma API, quem implementa apenas esse nível não pode ser considerada REST pois não segue qualquer padrão.

Um único verbo com nomes que não seguem nenhum padrão

Nível 1: Aplicação de Resources

Observe que o nome dos recursos foram equalizados e para não gerar ambiguidade é necessário definir o verbo apropriadamente.

Nível 2: Implementação de verbos HTTP

Como a definição dos verbos já foi requisitada no Nível 1, o Nível 2 se encarrega de validar a aplicabilidade dos verbos para finalidades específicas como:

Nível 3: HATEOAS

HATEOAS significa Hypermedia as the Engine of Application State. Uma API que implementa esse nível fornece aos seus clientes links que indicarão como poderá ser feita a navegação entre seus recursos. Ou seja, quem for consumir a API precisará saber apenas a rota principal e a resposta dessa requisição terá todas as demais rotas possíveis.

No exemplo acima, podemos ver o resultado de uma API que implementa HATEAOS, veja que na resposta dessa API há uma coleção “links”, cada link aponta para uma rota dessa API. No caso desse exemplo, temos um link para a própria rota, um link para alterar um cliente e outra para exlcuir.

▶️ Spring Web REST API

Para tornar o seu projeto uma aplicação web, basta que você adicione o starter spring-boot-starter-web conforme código abaixo:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Quando você adiciona a dependência <spring-boot-starter-web> em seu projeto Spring Boot, você está basicamente incluindo o Spring Web Starter, que é uma coleção de dependências que prepara seu projeto para criar aplicativos web baseados em Java. Aqui está o que acontece quando você adiciona essa dependência:

• Spring Web (spring-web): A biblioteca básica do Spring para desenvolvimento web, incluindo o suporte ao Spring MVC (Modelo-Visão-Controlador).
• Tomcat (ou outro servidor embutido): Por padrão, o Spring Boot inclui o Tomcat como servidor embutido, o que significa que seu aplicativo pode ser executado como uma aplicação autossuficiente sem precisar de um servidor externo.
• Jackson: Uma biblioteca para serialização e desserialização de objetos Java para e a partir de JSON. Ela é usada automaticamente para converter objetos Java em JSON quando você retorna dados em uma API REST, por exemplo.
• Spring Boot AutoConfiguration: O Starter Web também inclui a configuração automática para que, quando você usar o @SpringBootApplication e rodar o projeto, tudo seja configurado automaticamente para você, sem necessidade de configuração manual.
• Suporte a RESTful APIs: O Spring MVC funciona bem para expor seus recursos (como entidades Java) através de métodos HTTP (GET, POST, PUT, DELETE). O suporte ao formato JSON também é incluído automaticamente (via Jackson).

Com a dependência spring-boot-starter-web, o Spring Boot já vem configurado com Spring MVC. Isso permite que você crie controladores (controllers) e configure mapeamentos de URLs para os métodos do seu código, como:

• @Controller para construir páginas web (quando se trabalha com templates como Thymeleaf ou JSP).
• @RestController para construir APIs RESTful, onde os dados são geralmente retornados como JSON.

Exemplo básico de um controlador com Spring REST API:

@RestController
@RequestMapping("/ola-mundo")
public class MensagemController {

    @GetMapping
    public String getMensagem() {
        return "Olá, mundo! 🌍";
    }

}

application.properties

Além disso, você pode configurar diversas opções para sua aplicação web no arquivo application.properties ou application.yml. Por exemplo:

server.port=8081  # Configura a porta do servidor

Características principais do Recurso HTTP:

1. Representação de Dados: Um recurso é, geralmente, uma representação de dados, como um cliente, produto ou pedido. Essa representação é frequentemente serializada em JSON ou XML quando transmitida de volta ao cliente.
2. Interação via HTTP: Os recursos são acessados e manipulados usando os métodos HTTP. Por exemplo:

• GET /clientes: Recupera todos os clientes.
• POST /clientes: Cria um novo cliente.
• PUT /clientes/{id}: Atualiza um cliente existente.
• DELETE /clientes/{id}: Exclui um cliente específico.

3. Exposição de Dados: O recurso é geralmente manipulado através de controladores (controllers) em uma aplicação web. Um controlador pode acessar um repositório para buscar, criar ou modificar os dados, e então expor esses dados como recursos HTTP para o cliente.

Swagger

Swagger é uma linguagem de descrição de interface, para descrever APIs RESTful expressas usando JSON. O Swagger é usado junto com um conjunto de ferramentas de software de código aberto para projetar, construir, documentar e usar serviços da Web RESTful.

Abra o arquivo pom.xml e adicione as dependências do Swagger conforme código abaixo:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

▶️ @RestController

A anotação @RestController é a porta de entrada da aplicação. Este recurso é responsável por receber as requisições HTTP (como GET, POST, PUT, DELETE) e retornar respostas (normalmente objetos no formato JSON), podendo também retornar XML, imagens, pdf, Base64 entre outros.

Exemplo prático:

@RestController
@RequestMapping("/ola-mundo")
public class MensagemController {

    @GetMapping
    public String getMensagem() {
        return "Olá, mundo! 🌍";
    }
}

Nesse caso:

1. A URL /mensagem está exposta.
2. O cliente (navegador, front-end, Postman, etc.) faz um GET.
3. O controller responde com a mensagem no formato texto Olá, mundo! 🌍

O @RestController não depende das outras camadas. Ele pode usá-las, mas o seu foco principal é se comunicar com o mundo externo via HTTP.

▶️ Anotações

@RestController

• Marca uma classe como um controller REST, ou seja, que responde requisições HTTP com JSON ou String.
• Combina @Controller + @ResponseBody.
• Tudo que for retornado vai direto pro corpo da resposta.

@RestController
public class MeuController { }

@RequestMapping

• Define a rota base de um controller (ou pode ser usada em métodos também).
• Pode especificar método HTTP com method = RequestMethod.GET, mas normalmente usamos @GetMapping, @PostMapping etc.

@RequestMapping("/clientes")
public class ClienteController { }

@RequestParam

• Usado para pegar valores da URL no estilo query string: ?nome=Marcos.

@GetMapping("/saudacao")
public String saudar(@RequestParam String nome) {
    return "Olá, " + nome;
}
// Exemplo de chamada: GET /saudacao?nome=Marcos

@PathVariable

• Pega valores que estão na rota (dentro do caminho da URL).

@GetMapping("/usuarios/{id}")
public String buscarPorId(@PathVariable int id) {
    return "Usuário com ID: " + id;
}
// Exemplo: GET /usuarios/42

@RequestBody

• Usado em métodos POST/PUT para pegar um JSON enviado no corpo da requisição e transformar em um objeto Java.

@PostMapping("/usuarios")
public String criar(@RequestBody Usuario usuario) {
    return "Usuário criado: " + usuario.getNome();
}

Exemplo de JSON enviado:

{
  "nome": "Maria",
  "idade": 25
}

@ResponseStatus

• Define o código HTTP de resposta de forma explícita.

@PostMapping("/criar")
@ResponseStatus(HttpStatus.CREATED) // 201
public void criarAlgo() {
    // lógica
}

▶️ Verbos HTTP

Os verbos HTTP definem ações que podem ser executadas sobre os recursos disponíveis em um servidor. Cada verbo indica uma intenção específica, como buscar, criar, atualizar ou deletar dados.

Eles são fundamentais para construir APIs RESTful (algo que o Spring Web faz muito bem).

• Atalhos para métodos HTTP.
• Usados para expor rotas específicas com o tipo de operação.

@GetMapping, @PostMapping, @PutMapping, @DeleteMapping

▶️ Considerações

Usabilidade

@GetMapping

• Buscar dados
• Usado para listar ou buscar dados.
• Não altera nada no servidor.

@GetMapping("/usuarios")
public List<Usuario> listarUsuarios() { ... }

@GetMapping("/usuarios/{id}")
public Usuario buscarPorId(@PathVariable Long id) { ... }

@PostMapping

• Criar algo novo
• Usado para criar um novo recurso.
• Normalmente recebe dados com @RequestBody.

@PostMapping("/usuarios")
public Usuario criar(@RequestBody Usuario usuario) { ... }

@PutMapping

• Atualizar recurso inteiro
• Usado para substituir todos os dados de um recurso existente.
• Ideal quando você tem o objeto completo.

@PutMapping("/usuarios/{id}")
public Usuario atualizar(@PathVariable Long id, @RequestBody Usuario usuario) { ... }

@PatchMapping

• Atualizar parcialmente
• Usado para editar só parte de um recurso.
• Exemplo: só o nome, só o e-mail...

@PatchMapping("/usuarios/{id}")
public Usuario atualizarParcial(@PathVariable Long id, @RequestBody Map<String, Object> atualizacoes) { ... }

@DeleteMapping

• Deletar recurso
• Usado para remover um recurso.
• Não precisa de corpo (normalmente só o ID na URL).

@DeleteMapping("/usuarios/{id}")
public void deletar(@PathVariable Long id) { ... }

💡Memorize

Pense como se fosse uma ação em um sistema ou app:

• GET: "Quero ver isso"
• POST: "Quero adicionar isso"
• PUT: "Quero substituir isso"
• PATCH: "Quero corrigir/editar só um pedaço"
• DELETE: "Quero apagar isso"

Testando os serviços

O navegador consegue testar nossa aplicação somente com os métodos GET, mas como precisaremos realizar outros tipos de operações, será necessário ter um programa que interaja melhor com a API.

https://www.postman.com/downloads/

▶️ IzaBella

A IzaBella é uma loja dedicada a realçar a sua beleza com produtos escolhidos especialmente para atender os diferentes perfis de nossas clientes. Desde os itens essenciais até as últimas novidades do mercado, estamos aqui para oferecer tudo o que você precisa para se sentir ainda mais confiante e única.

Referências

• https://becode.com.br/o-que-e-api-rest-e-restful/
• https://4success.com.br/api-rest-e-restful/
• https://rivaildojunior.medium.com/modelo-de-maturidade-de-richardson-para-apis-rest-8845f93b288