Serviço

Com o Netuno é possível criar Web Services e construir qualquer tipo de APIs REST complexas para integração de dados entre sistemas.

O que é um Web Service?

Um Web Service permite que sistemas troquem informações online de forma padronizada. No Netuno, cada arquivo dentro de server/services/ se torna automaticamente um endpoint acessível via HTTP.

Por que usar Web Services?

O uso de serviços assíncronos traz benefícios claros para a experiência do usuário:

• Carregamento mais rápido: o servidor entrega a estrutura visual da página imediatamente, sem aguardar o processamento de todos os dados.
• Dados dinâmicos sobre demanda: o frontend solicita apenas os dados necessários, quando necessário.
• Integração entre sistemas: um serviço criado no Netuno pode ser consumido por qualquer aplicação externa (mobile, outro sistema web, etc.).
• Melhor experiência do usuário: o usuário não precisa aguardar o processamento completo da página antes de ver algo na tela.

Pré-requisitos

Antes de começar, certifique-se de que:

• O Netuno está instalado e em execução local.
• A aplicação demo foi criada conforme descrito em Criar Aplicação.
• Há dados cadastrados em Tarefas e relacionados com Registros (necessário para que o retorno não seja vazio).

Configurar o Editor de Código

Para criar e editar serviços no Netuno, utilize um editor de código de sua preferência. Recomendamos o Visual Studio Code por ser gratuito, leve e altamente intuitivo, mas qualquer editor compatível com JavaScript/Python/Groovy funcionará normalmente.

Abrir a Aplicação Demo

1. Abra o Visual Studio Code.
2. Clique no ícone de Arquivos no painel lateral esquerdo.
3. Selecione Abrir Pasta (File > Open Folder).
4. Navegue até a pasta de instalação do Netuno.
5. Selecione o diretório: apps/demo
6. Clique em Abrir.

A estrutura de pastas da aplicação demo será carregada no painel esquerdo.

Criar o Serviço

Os serviços são processados no lado do servidor. Para criar um novo serviço:

1. No painel de arquivos, expanda a estrutura até encontrar a pasta server/services/.
2. Clique com o botão direito sobre a pasta services.
3. Selecione Novo Arquivo New File.
4. Nomeie o arquivo de acordo com a linguagem que deseja usar:

JavaScript

• server/services/trabalhadores.js

Python

• server/services/trabalhadores.py

Ruby

• server/services/trabalhadores.rb

Kotlin

• server/services/trabalhadores.kts

Groovy

• server/services/trabalhadores.groovy

JavaScript

server/services/trabalhadores.js

/**
*** Transforma os dados da query em output JSON.
*/
const dbRegistros = _db.query(`
    SELECT DISTINCT
        trabalhador.nome, SUM(DATEDIFF(HOUR, registro.inicio, registro.fim)) AS total
    FROM trabalhador INNER JOIN registro
        ON trabalhador.id = registro.trabalhador_id
    WHERE trabalhador.active = true AND registro.active = true
    GROUP BY trabalhador.nome
    ORDER BY total ASC
`);

const lista = _val.list();

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

_out.json(lista);

Python

server/services/trabalhadores.py

#
# Transforma os dados da query em output JSON.
#
dbRegistros = _db.query(
    """SELECT DISTINCT
        trabalhador.nome, SUM(DATEDIFF(HOUR, registro.inicio, registro.fim)) AS total
    FROM trabalhador INNER JOIN registro
        ON trabalhador.id = registro.trabalhador_id
    WHERE trabalhador.active = true AND registro.active = true
    GROUP BY trabalhador.nome
    ORDER BY total ASC"""
)

lista = _val.list()

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

_out.json(lista)

Ruby

server/services/trabalhadores.rb

#
# Transforma os dados da query em output JSON.
#
dbRegistros = _db.query(%{
    SELECT DISTINCT
        trabalhador.nome, SUM(DATEDIFF(HOUR, registro.inicio, registro.fim)) AS total
    FROM trabalhador INNER JOIN registro
        ON trabalhador.id = registro.trabalhador_id
    WHERE trabalhador.active = true AND registro.active = true
    GROUP BY trabalhador.nome
    ORDER BY total ASC
})

lista = _val.list()

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

_out.json(lista)

Kotlin

server/services/trabalhadores.kts

/**
*** Transforma os dados da query em output JSON.
*/
val dbRegistros = _db.query(
    """SELECT DISTINCT
        trabalhador.nome, SUM(DATEDIFF(HOUR, registro.inicio, registro.fim)) AS total
    FROM trabalhador INNER JOIN registro
        ON trabalhador.id = registro.trabalhador_id
    WHERE trabalhador.active = true AND registro.active = true
    GROUP BY trabalhador.nome
    ORDER BY total ASC"""
)

val lista = _val.list()

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

_out.json(lista)

Groovy

server/services/trabalhadores.groovy

/**
*** Transforma os dados da query em output JSON.
*/
def dbRegistros = _db.query("""\
    SELECT DISTINCT
        trabalhador.nome, SUM(DATEDIFF(HOUR, registro.inicio, registro.fim)) AS total
    FROM trabalhador INNER JOIN registro
        ON trabalhador.id = registro.trabalhador_id
    WHERE trabalhador.active = true AND registro.active = true
    GROUP BY trabalhador.nome
    ORDER BY total ASC
""")

def lista = _val.list()

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

_out.json(lista)

Implemente o serviço adicionando o código abaixo ao arquivo criado. Este serviço consulta o banco de dados e retorna uma lista de trabalhadores com o total de horas registradas, no formato JSON.

Entendendo o Código

Objeto/Método	Descrição
_db.query()	Executa uma consulta SQL e retorna uma lista de objetos no formato chave-valor (coluna → dado).
_val.list()	Cria uma lista mutável para acumular os resultados.
_val.map()	Cria um objeto de mapeamento (chave-valor) para cada linha de resultado.
_out.json()	Serializa o objeto para JSON e envia a resposta as solicitações HTTP.

Dados necessários

Certifique-se de que há dados cadastrados em Tarefas e vinculados a Registros. Caso contrário, o endpoint retornará uma lista vazia [].

Executar e Testar o Serviço

Com o Netuno em execução, acesse o endpoint no navegador:

Dica para visualizar o JSON

Recomendamos o Firefox para testar endpoints diretamente no navegador, pois ele formata e exibe a resposta JSON de forma legível com destaque de sintaxe. Alternativamente, use extensões como JSON Viewer no Chrome ou ferramentas como o Postman para testes mais avançados.

O retorno esperado será um JSON semelhante a:

[
  { "name": "Ana Silva", "total": 12 },
  { "name": "Carlos Mendes", "total": 28 },
  { "name": "João Costa", "total": 45 }
]

Próximos Passos

Agora que seu serviço está funcionando, você pode:

• 📄 Interface & Design — integrar este serviço ao frontend da aplicação.
• 📚 Biblioteca de Serviços — explorar os objetos _db, _val, _out e outros disponíveis no Netuno.
• 🔗 Adicionar autenticação e controle de acesso ao seu serviço.

---