Proposta de boas práticas de rotas e controllers

Rotas atuais

Padronização

Vocabulário

Entidade

Objeto do banco de dados, parcialmente equivalente ao que seria uma linha da tabela.

Exemplos:

• Tracker
• User
• Alert

Propriedade

Atributo de um objeto do banco de dados, equivalente ao que seria uma coluna de uma linha da tabela, podendo também ser uma relação com outra entidade.

Exemplos:

• IsActive (do Tracker)
• IsOnline (do Tracker)
• Seen (do Notification)

Controller

Um controller deve ser responsável por uma única entidade. Toda atualização e leitura dessa entidade deve estar nesse controller.

Nomenclatura

Nome do controller: [Entitades]Controller (sempre no plural)

Exemplos:

• VansController
• StudentsController
• SchoolsController
• RoutesController
• ParentsController
• ReportsController
• DriversController

Modificações:

• VanOwnerController => OwnersController
• VanController => VansController
• UserController => UsersController
• criação do RouteEventsController (para rota de Post route/{id}/events que está no RoutesController)
• criação do CurrentRouteController (para rota de POST e DELETE van/current-route)
• NotificationController => NotificationsController

Exceções / o que fazer?

• AuthController
  • Não existe um conceito de "Auths" no banco de dados, é uma aglomeração de diferentes formas de login e autorização de aplicativos

Implementação

O controller deve se encontrar em: controllers/[entidades]/[entidades]Controller.cs

É importante que ele seja implementado como uma partial class para que cada rota seja implementada como uma extensão do controller em um arquivo próprio.

// Exemplo para um EntitiesController.cs no projeto VanEscola.Api
using Microsoft.AspNetCore.Mvc;
using VanEscola.Models;


namespace VanEscola.Api.Controllers
{
    public partial class EntitiesController : Controller
    {
        public EntitiesController(AppDbContext dbContext)
        {
            this.DbContext = dbContext;
        }

        public AppDbContext DbContext { get; private set; }
    }
}

Rotas

Estrutura de pastas

Cada rota deve ser um arquivo cujo nome reflete sua rota e método e deve se encontrar na pasta do seu controller.

Exemplo de projeto nessa estrutura de pastas

Perfis

No caso da API VanEscola, existem diferentes perfis de usuários que chamarão cada rota. Se a rota for um limitada para um perfil específico, o perfil deve prefixar a rota.

Exemplo:

• GET driver/user
• GET parent/user
• GET owner/user
• POST registration (pública)

Modificações:

• GET parents/vans => GET parent/vans
• GET van => GET driver/van
• POST/DELETE van/current-route => POST/DELETE driver/current-route
• Remover GET User (já existe GET driver/user)
• PUT change-password => PUT owner/change-password
• Remover GET Students (já existe GET driver/students)
• Remover GET Schools (já existe GET driver/schools)
• GET/POST/PUT/DELETE routes => GET/POST/PUT/DELETE driver/routes
• POST routes/{routeId}/events => POST driver/route-event
• PUT {routeId}/route-students ou PUT {routeId}/route-items => PUT driver/route/{routeId}/items
• GET reports => GET driver/reports
• GET notifications/messages => GET parent/notifications
• PUT notifications/seen => PUT parent/notifications/seen
• POST password => POST driver/change-password

Exceções / o que fazer?:

• POST van/locations-rnbg (chamada apenas por driver)

Padrões comuns de rotas

GET [Entidades]

Retorna uma lista com os dados de todas as entidades.

Exemplos:

• GET driver/students
• GET parent/students
• GET driver/schools
• GET owner/parents
• GET notifications/messages

GET [Entidade]

Retorna a única entidade relacionada ao usuário que a chamou.

Exemplos:

• GET van
• GET parent/user
• GET owner/user
• GET driver/user

POST [Entidade]

Cria uma entidade.

Exemplos:

• POST van/current-route
• POST owner/student
• POST owner/parent

Modificações:

• POST owner/schools => POST owner/school
• POST routes => POST route

DELETE [Entidade]

Deleta entidade do usuário (quando existe apenas uma entidade do usuário).

Exemplos:

• DELETE van/current-route
• DELETE auth/ticket

DELETE [Entidade]/{entidade-id}

Deleta entidade com entidade-id (quando podem existir múltiplas entidades de um mesmo usuário).

Exemplos:

• DELETE owner/student/{studentId}
• DELETE owner/parent/{parentId}

Modificações:

• DELETE owner/schools/{schoolId}/delete => DELETE owner/schools/{schoolId}
• DELETE routes/{routeId} => DELETE route/{routeId}

PUT [Entidade]

Atualiza dados da entidade do usuário (quando existe apenas uma entidade do usuário).

Exemplos:

• PUT owner/user

PUT [Entidade]/{entidade-id}

Atualiza os dados de uma entidade com entidade-id (quando podem existir múltiplas entidades de um mesmo usuário).

Exemplos:

• PUT owner/student/{student-id}
• PUT owner/parent/{parentId}

Modificações:

• PUT owner/user => PUT owner/user/{user-id}
• PUT owner/schools/{schoolId} => PUT owner/school/{schoolId}
• PUT routes/{routeId} => PUT route/{routeId}

PUT [Entidade]/{entidadeId}/[Propriedade]

Atualiza uma propriedade da entidade.

Exemplo:

• [NENHUM]

Modificações:

• PUT {routeId}/route-students => route/{routeId}/students
• POST/DELETE owner/parents/{parentId}/students/{studentId} => PUT owner/parents/{parentId}/students

PUT [Entidades]/[Propriedade]

Atualiza uma propriedade de várias entidades.

Exemplo:

• PUT notifications/seen