Pular para o conteúdo principal

Roteamento

O roteamento é uma das partes mais importantes na arquitetura de uma aplicação web, e no Nerdify isso foi elevado ao nível máximo de automação com organização.

🔗 Convenção de roteamento RESTful​

O padrão RESTful (Representational State Transfer) é uma convenção de arquitetura para APIs que define que cada recurso do sistema deve ser acessado por meio de uma rota baseada em sua identidade e ação correspondente.

Por exemplo:

  • GET /customers → lista de clientes
  • POST /customers → cria novo cliente
  • GET /customers/:id → exibe um cliente
  • PUT /customers/:id → atualiza cliente
  • DELETE /customers/:id → remove cliente

Esse padrão é previsível, facilita a manutenção e integração com o frontend e torna a API mais legível e intuitiva.

Além dessas rotas tradicionais, o Nerdify também adiciona ao modelo RESTful as rotas:

  • GET /customers/new
  • GET /customers/:id/edit

Essas rotas new e edit são normalmente usadas apenas em aplicações que renderizam views diretamente. No entanto, no Nerdify elas são utilizadas para retornar, via API, os componentes que o frontend precisa renderizar nas telas de criação e edição, bem como os resources preenchidos com dados ou parâmetros padrão. Isso torna possível montar a interface completa com um simples GET nessas rotas, mantendo a separação total entre frontend e backend.

📁 Rotas aninhadas e estrutura de pastas​

O Nerdify segue esse padrão RESTful automaticamente, graças à chamada:

Nerdify::Router.dynamic_routes

Esse comando, inserido no config/routes.rb da aplicação ao criar ou configurar uma aplicação nerdify através da CLI, é responsável por mapear dinamicamente todas as rotas com base na estrutura de pastas e controladores existentes.

✅ Quando o controlador pai existe:​

Se a aplicação tiver os seguintes controladores:

app/controllers/api/v1/companies_controller.rb
app/controllers/api/v1/companies/customers_controller.rb

A estrutura de pastas indica que Customer pertence a Company, e o Nerdify cria a rota aninhada:

/companies/:company_id/customers/:id

O backend receberá:

params[:company_id] # => 4
params[:id]         # => 7

@company  # => Company.find(4)
@customer # => Customer.find(7)

E irá instanciar o controlador Api::V1::Companies::CustomersController, que por convenção entende a relação entre os modelos e popula automaticamente os objetos @company e @customer.

Da mesma forma se você tentar criar um cliente através de um POST /api/v1/companies/:company_id/customers mesmo que não passe o :company_id no objeto json o vinculo será realizado automáticamente no controlador pelo aninhamento da rota antes de salvar no banco.

❌ Quando o controlador pai não existe:​

Caso exista apenas a estrutura de pastas:

app/controllers/api/v1/companies/customers_controller.rb

E não exista o controlador api/v1/companies_controller.rb, o Nerdify irá interpretar companies apenas como namespace, não como recurso pai.

A rota gerada será:

/companies/customers/:id

Nesse cenário, não haverá parâmetros como company_id, nem associação automática entre os modelos. O namespace será utilizado apenas para organizar o módulo, o que é útil para separar áreas da aplicação, como:

  • /api/v1/admin/... → área administrativa
  • /api/v1/platform/... → área principal da plataforma
  • /api/v1/public/... → uso externo ou público

🧭 A presença do controlador pai (companies_controller.rb) é o que determina se a estrutura será tratada como rota aninhada (com relacionamento entre modelos) ou apenas como namespace (estrutura de organização).