Service

With Netuno, you can create Web Services and build any type of complex REST APIs for data integration between systems.

What is a Web Service?

A Web Service allows systems to exchange information online in a standardized way. In Netuno, each file inside server/services/ automatically becomes an endpoint accessible via HTTP.

Why use Web Services?

Using asynchronous services brings clear benefits to the user experience:

Faster loading: the server delivers the page's visual structure immediately, without waiting for all data to be processed.
Dynamic data on demand: the frontend requests only the necessary data, when needed.
Integration between systems: a service created in Netuno can be consumed by any external application (mobile, another web system, etc.).
Better user experience: the user does not need to wait for the page to fully process before seeing something on the screen.

Prerequisites

Before you begin, make sure that:

Netuno is installed and running locally.
The demo application was created as described in Create Application.
There is data registered in Tasks and related to Records (required so the return is not empty).

Configure the Code Editor

To create and edit services in Netuno, use a code editor of your choice. We recommend Visual Studio Code because it is free, lightweight, and highly intuitive, but any editor compatible with JavaScript/Python/Groovy will work normally.

Open the Demo Application

Open Visual Studio Code.
Click the Files icon in the left sidebar.
Select Open Folder (File > Open Folder).
Navigate to the Netuno installation folder.
Select the directory: apps/demo
Click Open.

The demo application's folder structure will be loaded in the left panel.

Create the Service

Services are processed on the server side. To create a new service:

In the file panel, expand the structure until you find the server/services/ folder.
Right-click the services folder.
Select New File New File.
Name the file according to the language you want to use:

server/services/workers.js

server/services/workers.ts

server/services/workers.py

server/services/workers.rb

server/services/workers.kts

server/services/workers.groovy

server/services/workers.js
/**
*** Transforms the query data into JSON output.
*/
const dbRecords = _db.query(`
    SELECT DISTINCT
        worker.name, SUM(DATEDIFF(HOUR, record.start, record.end)) AS total
    FROM worker INNER JOIN record
        ON worker.id = record.worker_id
    WHERE worker.active = true AND record.active = true
    GROUP BY worker.name
    ORDER BY total ASC
`);

const list = _val.list();

for (const dbRecord of dbRecords) {
    list.add(
        _val.map()
            .set("name", dbRecord.getString("name"))
            .set("total", dbRecord.getInt("total"))
    );
}

_out.json(list);

server/services/workers.ts
/**
*** Transforms the query data into JSON output.
*/
const dbRecords = _db.query(`
    SELECT DISTINCT
        worker.name, SUM(DATEDIFF(HOUR, record.start, record.end)) AS total
    FROM worker INNER JOIN record
        ON worker.id = record.worker_id
    WHERE worker.active = true AND record.active = true
    GROUP BY worker.name
    ORDER BY total ASC
`);

const list = _val.list();

for (const dbRecord of dbRecords) {
    list.add(
        _val.map()
            .set("name", dbRecord.getString("name"))
            .set("total", dbRecord.getInt("total"))
    );
}

_out.json(list);

server/services/workers.py
#
# Transforms the query data into JSON output.
#
dbRecords = _db.query(
    """SELECT DISTINCT
        worker.name, SUM(DATEDIFF(HOUR, record.start, record.end)) AS total
    FROM worker INNER JOIN record
        ON worker.id = record.worker_id
    WHERE worker.active = true AND record.active = true
    GROUP BY worker.name
    ORDER BY total ASC"""
)

list = _val.list()

for dbRecord in dbRecords:
    list.add(
        _val.map()
            .set("name", dbRecord.getString("name"))
            .set("total", dbRecord.getInt("total"))
    )

_out.json(list)

server/services/workers.rb
#
# Transforms the query data into JSON output.
#
dbRecords = _db.query(%{
    SELECT DISTINCT
        worker.name, SUM(DATEDIFF(HOUR, record.start, record.end)) AS total
    FROM worker INNER JOIN record
        ON worker.id = record.worker_id
    WHERE worker.active = true AND record.active = true
    GROUP BY worker.name
    ORDER BY total ASC
})

list = _val.list()

dbRecords.each do |dbRecord|
    list.add(
        _val.map()
            .set("name", dbRecord.getString("name"))
            .set("total", dbRecord.getInt("total"))
    )
end

_out.json(list)

server/services/workers.kts
/**
*** Transforms the query data into JSON output.
*/
val dbRecords = _db.query(
    """SELECT DISTINCT
        worker.name, SUM(DATEDIFF(HOUR, record.start, record.end)) AS total
    FROM worker INNER JOIN record
        ON worker.id = record.worker_id
    WHERE worker.active = true AND record.active = true
    GROUP BY worker.name
    ORDER BY total ASC"""
)

val list = _val.list()

dbRecords.forEach {
    list.add(
        _val.map()
            .set("name", it.getString("name"))
            .set("total", it.getInt("total"))
    )
}

_out.json(list)

server/services/workers.groovy
/**
*** Transforms the query data into JSON output.
*/
def dbRecords = _db.query("""\
    SELECT DISTINCT
        worker.name, SUM(DATEDIFF(HOUR, record.start, record.end)) AS total
    FROM worker INNER JOIN record
        ON worker.id = record.worker_id
    WHERE worker.active = true AND record.active = true
    GROUP BY worker.name
    ORDER BY total ASC
""")

def list = _val.list()

for (dbRecord in dbRecords) {
    list.add(
        _val.map()
            .set("name", dbRecord.getString("name"))
            .set("total", dbRecord.getInt("total"))
    )
}

_out.json(list)

Implement the service by adding the code below to the file you created. This service queries the database and returns a list of workers with the total number of recorded hours in JSON format.

Understanding the Code

Object/Method	Description
`_db.query()`	Executes an SQL query and returns a list of key-value objects (column → data).
`_val.list()`	Creates a mutable list to accumulate the results.
`_val.map()`	Creates a mapping object (key-value) for each result row.
`_out.json()`	Serializes the object to JSON and sends the response to HTTP requests.

Required data

Make sure there is data registered in Tasks and linked to Records. Otherwise, the endpoint will return an empty list [].

Run and Test the Service

With Netuno running, open the endpoint in your browser:

Tip for viewing the JSON

We recommend Firefox for testing endpoints directly in the browser, as it formats and displays the JSON response legibly with syntax highlighting. Alternatively, use extensions such as JSON Viewer in Chrome or tools such as Postman for more advanced testing.

The expected return will be a JSON similar to:

[
  { "name": "Anna Smith", "total": 12 },
  { "name": "Charles Miller", "total": 28 },
  { "name": "John Costa", "total": 45 }
]

Next Steps

Now that your service is working, you can:

📄 Interface & Design — integrate this service into the application frontend.
📚 Services Library — explore the _db, _val, _out, and other objects available in Netuno.
🔗 Add authentication and access control to your service.

Why use Web Services?​

Prerequisites​

Configure the Code Editor​

Open the Demo Application​

Create the Service​

Understanding the Code​

Run and Test the Service​

Next Steps​