academia/docs/architecture/decisions/ADR-002-graphql-vs-rest.md

ADR-002: GraphQL vs REST

Estado: Aceptado Fecha: 2026-01-07

Contexto

La aplicación tiene relaciones complejas:

• Estudiantes → Inscripciones → Materias → Profesores
• Consultas como "materias disponibles" requieren múltiples joins
• Frontend necesita flexibilidad en datos solicitados

Decisión

Usar GraphQL con HotChocolate como API.

Consecuencias

Positivas

• No over-fetching: Cliente pide solo campos necesarios
• No under-fetching: Una query obtiene datos relacionados
• Schema tipado: Contrato explícito frontend-backend
• Playground incluido: Banana Cake Pop para testing
• DataLoaders: Resuelve N+1 automáticamente

Negativas

• Complejidad adicional vs REST simple
• Curva de aprendizaje GraphQL
• Requiere configurar query complexity limits
• Cache más complejo que HTTP caching

Ejemplo Comparativo

REST (múltiples requests)

GET /students/1
GET /students/1/enrollments
GET /subjects/1
GET /professors/1

GraphQL (una query)

query {
  student(id: 1) {
    name
    enrollments {
      subject {
        name
        professor { name }
      }
    }
  }
}

Alternativas

Alternativa	Razón de Descarte
REST	Over/under-fetching, múltiples endpoints
OData	Menos flexible, menos ecosistema
gRPC	No ideal para frontend web

Referencias

• HotChocolate Docs