Workshop: Como Construir uma API Laravel da Forma Correta

O workshop começou desconstruindo o mito de que construir API é complicado: bateu-se de frente com o hype em torno de GraphQL ("delírio coletivo", segundo o Danilo) e reforçou que uma API rodando sobre HTTP com GET/POST/PUT/DELETE retornando JSON já é REST — RESTful "by the book" é regra que na prática ninguém segue à risca. A partir daí, o Virgão desenvolveu ao vivo uma API para um app de busca de oficinas mecânicas ("tem carro estranho na cidade pequena? acha o mecânico especialista"), cobrindo modelagem de banco, autenticação, upload de arquivo em bucket e consumo via Flutter Flow.

Destaques

• Modelagem de banco com convenção de nomenclatura do Laravel: tabelas pivô em ordem alfabética e singular (car_repair_shop, car_user), make:model com -m -s -f -p para gerar migration/seeder/factory/pivot automaticamente.
• Discussão prática Sanctum vs Passport: Sanctum resolve 100% dos casos de API consumida só pelo próprio app; Passport (OAuth2) só faz sentido quando terceiros vão acessar dados do usuário (tipo "login com Google") ou para montar um SSO corporativo.
• Arquitetura em camadas simples e sem modismo: Controller → FormRequest (validação) → Service (regra de negócio) → API Resource (formatação de saída), reaproveitando essa camada de serviço entre API e web/Livewire sem duplicar lógica.
• Uso de Illuminate\Validation\ValidationException para erros de login, throttle nas rotas de autenticação para mitigar brute force, e HasApiTokens no model de usuário para habilitar Sanctum.
• API Resources (JsonResource) para nunca vazar campos sensíveis (senha, IDs indevidos), usar whenLoaded() para carregar relacionamentos só quando necessário, e Model::withoutWrapping() para remover o envelope data padrão.
• Upload de arquivo com Storage, driver S3 apontado para MinIO local (mesmo driver funciona para AWS S3, OCI Bucket, DigitalOcean Spaces), bucket privado por padrão e geração de URL temporária assinada (Storage::temporaryUrl()) só na hora de exibir a imagem.
• Query geográfica com selectRaw e fórmula de distância por latitude/longitude (Haversine) para ordenar oficinas por proximidade, usando bindings para evitar SQL injection.
• Integração ponta a ponta com Flutter Flow: variáveis de ambiente para base URL via ngrok, mapeamento de JSON path das respostas do Resource, autenticação por token em rotas protegidas e debug ao vivo de erros 500/422 usando Laravel Dumps.

Profundidade tecnica

O nível técnico foi de intermediário para avançado: a modelagem de dados e a camada de autenticação foram tratadas com rigor de convenção (nomenclatura, constraints de FK, tabelas pivô com colunas extras), mas o verdadeiro valor esteve nas decisões de arquitetura explicadas em tempo real — por que não inventar repository pattern, DDD ou arquitetura hexagonal em projetos que não precisam disso, e por que a estrutura padrão do Laravel (controller + FormRequest + Resource, mais uma camada opcional de Service) já é suficiente e escalável para a maioria dos casos. As armadilhas mais discutidas foram erros de configuração do storage/S3 (path prefix, driver local vs s3), a diferença entre gerar URL pública vs privada assinada, e cuidados de segurança em queries raw. Também houve uma reflexão honesta sobre quando vale a pena ter app nativo (Flutter Flow) versus web responsivo, e sobre as dores reais de publicação em App Store/Play Store.

Faça parte do Clã

Se você trava toda vez que precisa sair do CRUD básico e estruturar uma API do zero — autenticação, upload de arquivo, padronização de resposta, modelagem de relacionamento — esse tipo de workshop ao vivo, com erro real acontecendo na tela e resolvido em tempo real, é só uma fração do que rola dentro do Clã Beer and Code. Lá você tem acesso à metodologia completa (fundamentos, especialização Laravel, projetos práticos de ponta a ponta, deploy e escalabilidade), mentoria, comunidade ativa e todos os workshops gravados sem pagar de novo. Bora dar esse próximo passo.