🌐 Atividade 14: Modelagem de APIs REST e Swagger

🎯 Objetivo da Aula

Ao final desta atividade, você será capaz de:

• Mapear recursos de sistemas no formato e boas práticas de APIs REST.
• Utilizar os Verbos HTTP (GET, POST, PUT, DELETE) e os Códigos de Retorno (Status Codes) corretos.
• Escrever payloads estruturados em formato JSON (JavaScript Object Notation).
• Interpretar e projetar documentações no padrão Swagger/OpenAPI.

🏢 O Cenário Prático (Seu Desafio)

Na TecProExpress, os motoristas que usam o aplicativo Android precisam enviar em tempo real a geolocalização do caminhão para o painel de controle do SAC. Além disso, o app precisa buscar a lista de entregas pendentes direto do servidor central. No entanto, os desenvolvedores Mobile e os programadores de Backend não combinaram o "formato de dados" e a comunicação travou!

O app móvel mandava POST /api/enviar_localizacao e o servidor dava erro de conexão porque esperava receber um formato diferente do JSON enviado pelo celular!

"Seu desafio como Designer de APIs é desenhar o contrato profissional de endpoints para a TecProExpress. Você criará a modelagem de recursos RESTful para /api/entregas e /api/motoristas/localizacao, definindo os verbos corretos, os dados em formato JSON e gerando a especificação profissional baseada em Swagger/OpenAPI."

🧠 Fundamentos: A Teoria Traduzida

Uma API (Application Programming Interface) é uma porta que permite que sistemas diferentes conversem de forma organizada. REST é o estilo arquitetural padrão da web.

Regras de Ouro do Design REST:

1. Recursos são Substantivos no Plural: Evite verbos no endereço!
   • Errado: POST /api/salvarMotorista
   • Certo: POST /api/motoristas
2. Use os Verbos HTTP Adequados:
   • GET: Busca um ou vários registros (Ex: GET /api/entregas).
   • POST: Cria um novo registro (Ex: POST /api/entregas).
   • PUT: Atualiza o registro inteiro por completo.
   • DELETE: Exclui um registro da base de dados.
3. Comunique-se por Status Codes:
   • 200 OK: Requisição de consulta ou alteração com sucesso.
   • 201 Created: Novo registro criado com sucesso (retorno típico de POST).
   • 400 Bad Request: Envio de dados incorretos ou campos faltantes.
   • 404 Not Found: O registro ou endpoint consultado não existe.
   • 500 Internal Server Error: Falha técnica no servidor (bug).

📊 Visualizando a Comunicação HTTP

📖 Exemplo Guiado: Especificação Swagger e Spring Boot

Abaixo, veja como expor e documentar um endpoint de criação de entrega.

🛠️ Código Java 17 no Spring Boot (O Controller REST):

@RestController
@RequestMapping("/api/entregas")
@Tag(name = "Entregas", description = "Gerenciamento de entregas da TecProExpress")
public class DeliveryRestController {

    @Autowired
    private DeliveryService service;

    @PostMapping
    @Operation(summary = "Criar nova entrega", description = "Cria uma entrega no banco de dados e aguarda motorista")
    public ResponseEntity<DeliveryResponse> criarEntrega(@RequestBody DeliveryRequest request) {
        DeliveryResponse response = service.criar(request);
        return ResponseEntity.status(HttpStatus.CREATED).body(response);
    }
}

📄 O Contrato JSON enviado pelo App Mobile (Payload):

{
  "clienteId": 45,
  "enderecoDestino": "Av. Paulista, 1000 - São Paulo, SP",
  "pesoCarga": 12.5,
  "tipoNotificacao": "SMS"
}

📄 Documentação Swagger (OpenAPI YAML) correspondente:

openapi: 3.0.3
info:
  title: API TecProExpress
  version: 1.0.0
paths:
  /api/entregas:
    post:
      summary: Criar nova entrega
      tags:
        - Entregas
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - clienteId
                - enderecoDestino
              properties:
                clienteId:
                  type: integer
                enderecoDestino:
                  type: string
                pesoCarga:
                  type: number
      responses:
        '201':
          description: Criado com sucesso

🛠️ Prática Obrigatória 1: Tabela de Endpoints da API

Cenário: O projeto semestral da sua equipe.

1. Mapeie 3 endpoints críticos que o seu sistema precisará expor para um aplicativo celular ou sistema parceiro.
2. Organize-os em uma tabela contendo: Verbo HTTP, Caminho (URL), O que faz (Descrição) e Status Code de Sucesso (ex: 200, 201).

🏁 Resultado Esperado (Para sua Referência)

Uma tabela com o roteiro de comunicação REST detalhando as requisições principais de forma limpa e seguindo as boas práticas.

🛠️ Prática Obrigatória 2: O Payload JSON e Contrato Swagger

Cenário: Detalhando os dados de tráfego.

1. Para o endpoint principal de inserção de dados da Prática 1 (Ex: criar agendamento, realizar venda), escreva o payload em formato JSON real que o cliente enviará.
2. Escreva a especificação profissional simplificada no padrão Swagger/OpenAPI (formato YAML) que descreve esse endpoint e o corpo da requisição de forma estruturada.

📤 Instruções de Entrega (Microsoft Teams)

Após validar o seu design de API:

1. Salve o arquivo contendo a tabela de endpoints, o JSON e a especificação Swagger YAML com o nome Atividade_14.md na pasta es-atv-14-apis-swagger/ do seu repositório GitHub.
2. Certifique-se de fazer o commit e push para o repositório público.
3. Submeta o link do seu repositório no Microsoft Teams para avaliação do professor.

💡 Checkpoint de Lógica

📊 Rubrica Formativa de Avaliação