🚀 Capítulo 16: O Arquiteto de APIs (Tema: Matrix)
NOTE
Este capítulo utiliza a temática de Matrix para explicar o planejamento de uma API RESTful profissional. Desenhe as regras e as rotas do seu sistema antes de codificar!
1. 🎯 Objetivo da Aula
Compreender os conceitos de uma arquitetura RESTful, como mapear os recursos da sua API para as rotas corretas e os métodos HTTP adequados para cada ação.
2. 🏢 O Cenário Prático (Seu Desafio)
Voltamos ao mundo de Matrix! O Arquiteto planejou minuciosamente cada porta de entrada, cada protocolo de comunicação e cada fluxo de dados que corre pelas veias do mundo digital. Ele sabe exatamente qual comando abre qual porta e o que cada usuário tem permissão de fazer.
Chegou a hora de você ser o Arquiteto da sua própria API profissional!
- Antes de abrir o VS Code e começar a digitar códigos de rotas aleatórios, um bom engenheiro de backend planeja a “Arquitetura” do sistema.
- Nós precisamos definir quais “Recursos” (ex: Usuários, Produtos, Pedidos) o nosso sistema vai gerenciar e quais caminhos (URLs) vamos liberar para o mundo externo acessar. Seu desafio é desenhar o mapa da Matrix!
🧠 Fundamentos: A Teoria Traduzida
🌐 1. O que é uma API RESTful?
É um padrão de organização de APIs web que usa os métodos HTTP de forma semântica (com significado) para gerenciar recursos.
🗺️ 2. O Mapeamento de Rotas Profissional:
Imagine que estamos gerenciando o recurso produtos. O padrão RESTful diz que devemos usar a mesma URL base e apenas mudar o Método HTTP e o ID para fazer ações diferentes:
GET /produtos: Retorna a lista de todos os produtos.POST /produtos: Cria um produto novo (enviando os dados no JSON).GET /produtos/:id: Busca os detalhes de um produto específico.PUT /produtos/:id: Atualiza os dados de um produto específico.DELETE /produtos/:id: Deleta um produto específico do banco de dados.
Repare como as URLs são limpas, fáceis de ler e usam substantivos no plural (produtos), nunca verbos como /criarProduto ou /deletarProduto.
4. 📖 Exemplo Guiado: O Checklist do Arquiteto
Para o recurso “Bruxos” da escola de magia, o Arquiteto desenha a seguinte tabela de rotas:
- Listar todos:
GET /bruxos - Buscar um:
GET /bruxos/:id - Criar novo:
POST /bruxos - Expulsar (deletar):
DELETE /bruxos/:id
5. 🛠️ Prática Obrigatória 1: Mapeando Rotas
Imagine que você está criando uma API para gerenciar “Músicas” em um aplicativo estilo Spotify. Seguindo o padrão RESTful ensinado acima, quais seriam as URLs e os Métodos HTTP corretos para:
- Listar todas as músicas disponíveis?
- Cadastrar uma música nova no sistema?
6. 🛠️ Prática Obrigatória 2: O ID na URL
- Por que em operações como buscar um produto específico ou deletar um produto nós precisamos colocar o
:idno final da URL (ex:DELETE /produtos/5) e na rota de criar um produto novo (POST /produtos) nós não precisamos colocar o ID?
7. 📤 Instruções de Entrega (GitHub Desktop + Microsoft Teams)
- Faça o Commit: No GitHub Desktop, digite a mensagem (ex:
Finaliza Capítulo 16 Go_Arquiteto) e clique em Commit to main. - Envie para a Nuvem (Push): Clique em Push origin.
8. 📂 Estrutura de Pastas
spec_backend_com_golang_e_gin/
├── capitulos/
│ └── capitulo_16_arquiteto.md💡 Checkpoint de Lógica
Em projetos grandes, os programadores de Go costumam separar o código em pastas como: /models (para as structs de banco), /controllers (para as funções das rotas) e /routes (apenas para mapear as URLs)!
10. 🔥 Desafio de Fixação
Pesquise o que significa o código de status HTTP 201 e em qual momento de uma API RESTful ele deve ser retornado para o usuário.
🔑 Gabarito de Código/Fórmulas
Gabarito da Prática 1:
GET /musicasPOST /musicasGabarito da Prática 2:- Porque para deletar ou buscar, nós precisamos dizer ao banco de dados exatamente qual registro queremos alterar (o de ID 5, por exemplo). Na rota de criação (
POST), nós ainda não sabemos qual será o ID do produto, pois é o banco de dados que vai gerar um ID novo para ele automaticamente após a criação!