Servicio

Con Netuno es posible crear servicios web y construir cualquier tipo de APIs REST complejas para la integración de datos entre sistemas.

¿Qué es un servicio web?

Un servicio web permite que los sistemas intercambien información en línea de forma estandarizada. En Netuno, cada archivo dentro de server/services/ se convierte automáticamente en un endpoint accesible vía HTTP.

¿Por qué usar servicios web?

El uso de servicios asíncronos aporta beneficios claros para la experiencia del usuario:

• Carga más rápida: el servidor entrega la estructura visual de la página de inmediato, sin esperar el procesamiento de todos los datos.
• Datos dinámicos bajo demanda: el frontend solicita solo los datos necesarios, cuando es necesario.
• Integración entre sistemas: un servicio creado en Netuno puede ser consumido por cualquier aplicación externa (móvil, otro sistema web, etc.).
• Mejor experiencia de usuario: el usuario no necesita esperar el procesamiento completo de la página antes de ver algo en pantalla.

Requisitos previos

Antes de comenzar, asegúrese de que:

• Netuno está instalado y en ejecución local.
• La aplicación demo se ha creado tal como se describe en Crear aplicación.
• Hay datos registrados en Tareas y relacionados con Registros (necesario para que el retorno no esté vacío).

Configurar el editor de código

Para crear y editar servicios en Netuno, utilice un editor de código de su preferencia. Recomendamos Visual Studio Code por ser gratuito, ligero y altamente intuitivo, pero cualquier editor compatible con JavaScript/Python/Groovy funcionará normalmente.

Abrir la Aplicación Demo

1. Abra Visual Studio Code.
2. Haga clic en el icono de Archivos del panel lateral izquierdo.
3. Seleccione Abrir carpeta (Archivo > Abrir carpeta).
4. Navegue hasta la carpeta de instalación de Netuno.
5. Seleccione el directorio: apps/demo
6. Haga clic en Abrir.

La estructura de carpetas de la aplicación demo se cargará en el panel izquierdo.

Crear el servicio

Los servicios se procesan en el lado del servidor. Para crear un nuevo servicio:

1. En el panel de archivos, expanda la estructura hasta encontrar la carpeta server/services/.
2. Haga clic con el botón derecho sobre la carpeta services.
3. Seleccione Nuevo archivo (Nuevo archivo).
4. Asigne un nombre al archivo según el lenguaje que desee usar:

JavaScript

• server/services/trabajadores.js

TypeScript

• server/services/trabajadores.ts

Python

• server/services/trabajadores.py

Ruby

• server/services/trabajadores.rb

Kotlin

• server/services/trabajadores.kts

Groovy

• server/services/trabajadores.groovy

JavaScript

server/services/trabajadores.js

/**
*** Transforma los datos de la consulta en salida JSON.
*/
const dbRegistros = _db.query(`
    SELECT DISTINCT
        trabajador.nombre, SUM(DATEDIFF(HOUR, registro.inicio, registro.fin)) AS total
    FROM trabajador INNER JOIN registro
        ON trabajador.id = registro.trabajador_id
    WHERE trabajador.activo = true AND registro.activo = true
    GROUP BY trabajador.nombre
    ORDER BY total ASC
`);

const lista = _val.list();

for (const dbRegistro of dbRegistros) {
    lista.add(
        _val.map()
            .set("nombre", dbRegistro.getString("nombre"))
            .set("total", dbRegistro.getInt("total"))
    );
}

_out.json(lista);

TypeScript

server/services/trabajadores.ts

/**
*** Transforma los datos de la consulta en salida JSON.
*/
const dbRegistros = _db.query(`
    SELECT DISTINCT
        trabajador.nombre, SUM(DATEDIFF(HOUR, registro.inicio, registro.fin)) AS total
    FROM trabajador INNER JOIN registro
        ON trabajador.id = registro.trabajador_id
    WHERE trabajador.activo = true AND registro.activo = true
    GROUP BY trabajador.nombre
    ORDER BY total ASC
`);

const lista = _val.list();

for (const dbRegistro of dbRegistros) {
    lista.add(
        _val.map()
            .set("nombre", dbRegistro.getString("nombre"))
            .set("total", dbRegistro.getInt("total"))
    );
}

_out.json(lista);

Python

server/services/trabajadores.py

#
# Transforma los datos de la consulta en salida JSON.
#
dbRegistros = _db.query(
    """SELECT DISTINCT
        trabajador.nombre, SUM(DATEDIFF(HOUR, registro.inicio, registro.fin)) AS total
    FROM trabajador INNER JOIN registro
        ON trabajador.id = registro.trabajador_id
    WHERE trabajador.activo = true AND registro.activo = true
    GROUP BY trabajador.nombre
    ORDER BY total ASC"""
)

lista = _val.list()

for dbRegistro in dbRegistros:
    lista.add(
        _val.map()
            .set("nombre", dbRegistro.getString("nombre"))
            .set("total", dbRegistro.getInt("total"))
    )

_out.json(lista)

Ruby

server/services/trabajadores.rb

#
# Transforma los datos de la consulta en salida JSON.
#
dbRegistros = _db.query(%{
    SELECT DISTINCT
        trabajador.nombre, SUM(DATEDIFF(HOUR, registro.inicio, registro.fin)) AS total
    FROM trabajador INNER JOIN registro
        ON trabajador.id = registro.trabajador_id
    WHERE trabajador.activo = true AND registro.activo = true
    GROUP BY trabajador.nombre
    ORDER BY total ASC
})

lista = _val.list()

dbRegistros.each do |dbRegistro|
    lista.add(
        _val.map()
            .set("nombre", dbRegistro.getString("nombre"))
            .set("total", dbRegistro.getInt("total"))
    )
end

_out.json(lista)

Kotlin

server/services/trabajadores.kts

/**
*** Transforma los datos de la consulta en salida JSON.
*/
val dbRegistros = _db.query(
    """SELECT DISTINCT
        trabajador.nombre, SUM(DATEDIFF(HOUR, registro.inicio, registro.fin)) AS total
    FROM trabajador INNER JOIN registro
        ON trabajador.id = registro.trabajador_id
    WHERE trabajador.activo = true AND registro.activo = true
    GROUP BY trabajador.nombre
    ORDER BY total ASC"""
)

val lista = _val.list()

dbRegistros.forEach {
    lista.add(
        _val.map()
            .set("nombre", it.getString("nombre"))
            .set("total", it.getInt("total"))
    )
}

_out.json(lista)

Groovy

server/services/trabajadores.groovy

/**
*** Transforma los datos de la consulta en salida JSON.
*/
def dbRegistros = _db.query("""\
    SELECT DISTINCT
        trabajador.nombre, SUM(DATEDIFF(HOUR, registro.inicio, registro.fin)) AS total
    FROM trabajador INNER JOIN registro
        ON trabajador.id = registro.trabajador_id
    WHERE trabajador.activo = true AND registro.activo = true
    GROUP BY trabajador.nombre
    ORDER BY total ASC
""")

def lista = _val.list()

for (dbRegistro in dbRegistros) {
    lista.add(
        _val.map()
            .set("nombre", dbRegistro.getString("nombre"))
            .set("total", dbRegistro.getInt("total"))
    )
}

_out.json(lista)

Implemente el servicio añadiendo el código siguiente al archivo creado. Este servicio consulta la base de datos y devuelve una lista de trabajadores con el total de horas registradas, en formato JSON.

Entendiendo el código

Objeto/Método	Descripción
_db.query()	Ejecuta una consulta SQL y devuelve una lista de objetos en formato clave-valor (columna → dato).
_val.list()	Crea una lista mutable para acumular los resultados.
_val.map()	Crea un objeto de mapeo (clave-valor) para cada fila de resultado.
_out.json()	Serializa el objeto a JSON y envía la respuesta a las solicitudes HTTP.

Datos necesarios

Asegúrese de que hay datos registrados en Tareas y vinculados a Registros. De lo contrario, el endpoint devolverá una lista vacía [].

Ejecutar y probar el servicio

Con Netuno en ejecución, acceda al endpoint en el navegador:

Consejo para visualizar el JSON

Recomendamos Firefox para probar endpoints directamente en el navegador, ya que formatea y muestra la respuesta JSON de forma legible con resaltado de sintaxis. Alternativamente, use extensiones como JSON Viewer en Chrome o herramientas como Postman para pruebas más avanzadas.

El retorno esperado será un JSON similar a:

[
  { "nombre": "Ana Silva", "total": 12 },
  { "nombre": "Carlos Mendes", "total": 28 },
  { "nombre": "Juan Costa", "total": 45 }
]

Próximos pasos

Ahora que su servicio está funcionando, puede:

• 📄 Interfaz y diseño — integrar este servicio en el frontend de la aplicación.
• 📚 Biblioteca de servicios — explorar los objetos _db, _val, _out y otros disponibles en Netuno.
• 🔗 Añadir autenticación y control de acceso a su servicio.

---