Skip to content

Backend's REST API

Jump to bottom
Gualter Machado edited this page Sep 29, 2023 · 14 revisions

This wiki page serves to instruct how to use the application's REST API, as well as to document each endpoint's functionality.

Usage

Connecting to the web server

By default, the web server runs on address http://localhost:50000/. You can change the address in the webserver.go file (look for the router.Run line). All endpoints listed in this page are executed by appending the endpoint address to the base server URL (that is, the endpoint /devices is acessed with the URL http://localhost:50000/devices

Check your list of network interfaces

Make a GET request to /devices to get a list of all network interfaces that can be monitored on your machine. The "Description" field is the interface's name identification, while the "Name" field is the interface's address. Take note of the interface's address you wish to monitor.
Warning: The addresses contain double backslashes (\\). This is to indicate a normal, single backslash, but the API returns the addresses with double backslashes. When setting the desired network interface, you must send the address with a single backslash!

Set the desired network interface

Make a POST request to /devices. The request's body must contain an "interface" (case-sensitive) field, and its value should be the desired network interface's address. You can change the interface afterwards using the same endpoint, but you must set it at least once to run the network traffic monitor tool. If you get a message back from the server saying Device set, you're good to go!

Check your network activity in real time

Connect to the Websocket in the address ws://localhost:50000/ws to view your network activity. The websocket outputs the accumulated network activity within the previous second. This lets you view each application's network consumption as well as each subprocess, protocol and host activity associated to it.

Consult your network activity and consumption statistics

The application stores your network activity in a database every 5 minutes. This database is local and can be only accessed from your machine. It is located in the application's folder and is named database.db. You can check for individual applications, subprocesses, protocols and hosts as well as network consumption statistics associated with them using the endpoints below.

Endpoints

Devices

This section covers all endpoints related to retrieving and setting network devices.

GET

/devices

  • Returns a list of all network interfaces available to be monitored on this machine.
  • Path Parameters: None
  • Query Parameters: None
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
[
  {
    "Index": "indexNumber",
    "Description": "Device's name identification",
    "Name": "Device's address"
  }
]
  • On failed request:
    • HTTP Code: 404 Not Found
    • Response Body:
{"error": "Unable to retrieve interfaces"}

POST

/devices

  • Set the desired network interface.
  • Body Parameters: *interface: string -> Network interface's address. (Mandatory)
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
{"message": "Device set"}
  • On failed request:
    • HTTP Code: 404 Not Found
    • Response Body:
{"error": "Unable to locate device"}
{"error": "Unable to retrieve interfaces"}

Statistics

This section covers all endpoints related to retrieving network consumption statistics.

GET

/statistics

  • Returns the total network consumption divided by download and upload. A time frame can be used to filter the results.
  • Query Parameters:
    • initialDate: number -> Initial time in the timeframe, in Unix timestamp in millis
    • endDate: number -> Final time in the timeframe, in Unix timestamp in millis
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
{
    "total_upload": "Total upload",
    "total_download": "Total download",
    "total": "Sum of download and upload"
}
  • On failed request:
    • HTTP Code: 500 Internal Server Error
    • Response Body:
{"error": "SQL Error Message"}

Active Processes (Application)

This section covers all endpoints related to retrieving entries and statistics related to the active processes (i.e. applications running on your machine).

GET

/active-processes

  • Returns a list of all applications stored in the database. A time frame can be used to filter the applications.
  • Query Parameters:
    • initialDate: number -> Initial time in the timeframe, in Unix timestamp in millis
    • endDate: number -> Final time in the timeframe, in Unix timestamp in millis
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
[
{
        "name": "App name",
        "update_time": "Last time updated",
        "upload": "Total upload",
        "download": "Total download",
        "processes": {
            "PID": {
                "pid": "PID",
                "create_time": "Time of creation",
                "upload": "Total upload",
                "download": "Total download"
            }
        },
        "protocols": {
            "protocol": {
                "protocol_name": "protocol",
                "upload": "Total upload",
                "download": "Total download"
            }
        },
        "hosts": {
            "host": {
                "host_name": "host",
                "upload": "Total upload",
                "download": "Total download"
            }
        }
    },
]
  • On failed request:
    • HTTP Code: 500 Internal Server Error
    • Response Body:
{"error": "SQL Error Message"}

/active-processes/{name}

  • Returns a list of all applications of a given name stored in the database. A time frame can be used to filter the applications.
  • Path Parameters:
    • name: string -> Full name of the application, including the extension
  • Query Parameters:
    • initialDate: number -> Initial time in the timeframe, in Unix timestamp in millis
    • endDate: number -> Final time in the timeframe, in Unix timestamp in millis
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
[
{
        "name": "App name",
        "update_time": "Last time updated",
        "upload": "Total upload",
        "download": "Total download",
        "processes": {
            "PID": {
                "pid": "PID",
                "create_time": "Time of creation",
                "upload": "Total upload",
                "download": "Total download"
            }
        },
        "protocols": {
            "protocol": {
                "protocol_name": "protocol",
                "upload": "Total upload",
                "download": "Total download"
            }
        },
        "hosts": {
            "host": {
                "host_name": "host",
                "upload": "Total upload",
                "download": "Total download"
            }
        }
    },
]
  • On failed request:
    • HTTP Code: 500 Internal Server Error
    • Response Body:
{"error": "SQL Error Message"}

/active-processes/statistics/{name}

  • Returns a network consumption statistics of a given application stored in the database. A time frame can be used to filter the applications.
  • Path Parameters:
    • name: string -> Full name of the application, including the extension
  • Query Parameters:
    • initialDate: number -> Initial time in the timeframe, in Unix timestamp in millis
    • endDate: number -> Final time in the timeframe, in Unix timestamp in millis
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
{
    "Application name": {
        "name": "Application name",
        "total_upload": "Total upload",
        "total_download": "Total download",
        "total": "Sum of upload and download"
    }
}
  • On failed request:
    • HTTP Code: 500 Internal Server Error
    • Response Body:
{"error": "No data available"}

/active-processes/statistics/entries

  • Returns a network consumption statistics of all applications stored in the database. A time frame can be used to filter the applications.
  • Query Parameters:
    • initialDate: number -> Initial time in the timeframe, in Unix timestamp in millis
    • endDate: number -> Final time in the timeframe, in Unix timestamp in millis
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
[
    {
        "Application name": {
            "name": "Application name",
            "total_upload": "Total upload",
            "total_download": "Total download",
            "total": "Sum of upload and download"
        }
    },
]
  • On failed request:
    • HTTP Code: 500 Internal Server Error
    • Response Body:
{"error": "No data available"}

Processes (Application's individual processes)

This section covers all endpoints related to retrieving entries and statistics related to the individual processes of an application.

GET

/processes

  • Returns a list of all processes stored in the database. A time frame can be used to filter the applications.
  • Query Parameters:
    • initialDate: number -> Initial time in the timeframe, in Unix timestamp in millis
    • endDate: number -> Final time in the timeframe, in Unix timestamp in millis
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
[
{
        "PID": {
                "pid": "PID",
                "create_time": "Time of creation",
                "upload": "Total upload",
                "download": "Total download"
        }
},
]
  • On failed request:
    • HTTP Code: 500 Internal Server Error
    • Response Body:
{"error": "SQL Error Message"}

/processes/{pid}

  • Returns a list of all processes of a given PID stored in the database. A time frame can be used to filter the applications.
  • Path Parameters:
    • pid: number -> The process' ID
  • Query Parameters:
    • initialDate: number -> Initial time in the timeframe, in Unix timestamp in millis
    • endDate: number -> Final time in the timeframe, in Unix timestamp in millis
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
[
{
        "PID": {
                "pid": "PID",
                "create_time": "Time of creation",
                "upload": "Total upload",
                "download": "Total download"
        }
},
]
  • On failed request:
    • HTTP Code: 500 Internal Server Error
    • Response Body:
{"error": "SQL Error Message"}

/processes/statistics/{pid}

  • Returns a network consumption statistics regarding a given process stored in the database. A time frame can be used to filter the applications.
  • Path Parameters:
    • pid: number -> The process' ID
  • Query Parameters:
    • initialDate: number -> Initial time in the timeframe, in Unix timestamp in millis
    • endDate: number -> Final time in the timeframe, in Unix timestamp in millis
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
{
        "PID": {
                "name": "PID",
                "total_upload": "Total upload",
                "total_download": "Total download",
                "total": "Sum of upload and download"
        }
}
  • On failed request:
    • HTTP Code: 500 Internal Server Error
    • Response Body:
{"error": "No data available"}

/processes/statistics/entries

  • Returns a network consumption statistics of all processes stored in the database. A time frame can be used to filter the applications.
  • Query Parameters:
    • initialDate: number -> Initial time in the timeframe, in Unix timestamp in millis
    • endDate: number -> Final time in the timeframe, in Unix timestamp in millis
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
[
{
        "PID": {
                "name": "PID",
                "total_upload": "Total upload",
                "total_download": "Total download",
                "total": "Sum of upload and download"
        }
},
]
  • On failed request:
    • HTTP Code: 500 Internal Server Error
    • Response Body:
{"error": "No data available"}

Protocols

This section covers all endpoints related to retrieving entries and statistics related to the Application Layer protocols used during communication. The protocol can be either the well known name of a given port, or only the port number. The port number used is always from the remote host.

GET

/protocols

  • Returns a list of all protocols stored in the database. A time frame can be used to filter the applications.
  • Query Parameters:
    • initialDate: number -> Initial time in the timeframe, in Unix timestamp in millis
    • endDate: number -> Final time in the timeframe, in Unix timestamp in millis
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
[
{
        "Protocol": {
                "protocol_name": "Protocol",
                "upload": "Total upload",
                "download": "Total download"
        }
},
]
  • On failed request:
    • HTTP Code: 500 Internal Server Error
    • Response Body:
{"error": "SQL Error Message"}

/protocols/{name}

  • Returns a list of all protocols of a given name stored in the database. A time frame can be used to filter the applications.
  • Path Parameters:
    • name: string -> The protocol name. This parameter must be formatted as port_number(protocol_name), like 443(https).
  • Query Parameters:
    • initialDate: number -> Initial time in the timeframe, in Unix timestamp in millis
    • endDate: number -> Final time in the timeframe, in Unix timestamp in millis
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
[
{
        "Protocol": {
                "protocol_name": "Protocol",
                "upload": "Total upload",
                "download": "Total download"
        }
},
]
  • On failed request:
    • HTTP Code: 500 Internal Server Error
    • Response Body:
{"error": "SQL Error Message"}

/protocols/statistics/{name}

  • Returns a network consumption statistics regarding a given protocol stored in the database. A time frame can be used to filter the applications.
  • Path Parameters:
    • name: string -> The protocol name. This parameter must be formatted as port_number(protocol_name), like 443(https).
  • Query Parameters:
    • initialDate: number -> Initial time in the timeframe, in Unix timestamp in millis
    • endDate: number -> Final time in the timeframe, in Unix timestamp in millis
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
{
        "PID": {
                "name": "PID",
                "total_upload": "Total upload",
                "total_download": "Total download",
                "total": "Sum of upload and download"
        }
}
  • On failed request:
    • HTTP Code: 500 Internal Server Error
    • Response Body:
{"error": "No data available"}

/protocols/statistics/entries

  • Returns a network consumption statistics of all processes stored in the database. A time frame can be used to filter the applications.
  • Query Parameters:
    • initialDate: number -> Initial time in the timeframe, in Unix timestamp in millis
    • endDate: number -> Final time in the timeframe, in Unix timestamp in millis
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
[
{
        "PID": {
                "name": "PID",
                "total_upload": "Total upload",
                "total_download": "Total download",
                "total": "Sum of upload and download"
        }
},
]
  • On failed request:
    • HTTP Code: 500 Internal Server Error
    • Response Body:
{"error": "No data available"}

Hosts

This section covers all endpoints related to retrieving entries and statistics related to the remote hosts that were contacted during a communication. The host can be an IPv4 or an IPv6 address.

GET

/hosts

  • Returns a list of all hosts stored in the database. A time frame can be used to filter the applications.
  • Query Parameters:
    • initialDate: number -> Initial time in the timeframe, in Unix timestamp in millis
    • endDate: number -> Final time in the timeframe, in Unix timestamp in millis
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
[
{
        "Host": {
                "host_name": "Host",
                "upload": "Total upload",
                "download": "Total download"
        }
},
]
  • On failed request:
    • HTTP Code: 500 Internal Server Error
    • Response Body:
{"error": "SQL Error Message"}

/hosts/{name}

  • Returns a list of all hosts of a given name stored in the database. A time frame can be used to filter the applications.
  • Path Parameters:
    • name: string -> The remote host's IP address.
  • Query Parameters:
    • initialDate: number -> Initial time in the timeframe, in Unix timestamp in millis
    • endDate: number -> Final time in the timeframe, in Unix timestamp in millis
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
[
{
        "Host": {
                "host_name": "Host",
                "upload": "Total upload",
                "download": "Total download"
        }
},
]
  • On failed request:
    • HTTP Code: 500 Internal Server Error
    • Response Body:
{"error": "SQL Error Message"}

/hosts/statistics/{name}

  • Returns a network consumption statistics regarding a given host stored in the database. A time frame can be used to filter the applications.
  • Path Parameters:
    • name: string -> The remote host's IP address.
  • Query Parameters:
    • initialDate: number -> Initial time in the timeframe, in Unix timestamp in millis
    • endDate: number -> Final time in the timeframe, in Unix timestamp in millis
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
{
        "Host": {
                "name": "Host",
                "total_upload": "Total upload",
                "total_download": "Total download",
                "total": "Sum of upload and download"
        }
}
  • On failed request:
    • HTTP Code: 500 Internal Server Error
    • Response Body:
{"error": "No data available"}

/hosts/statistics/entries

  • Returns a network consumption statistics of all hosts stored in the database. A time frame can be used to filter the applications.
  • Query Parameters:
    • initialDate: number -> Initial time in the timeframe, in Unix timestamp in millis
    • endDate: number -> Final time in the timeframe, in Unix timestamp in millis
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
[
{
        "Host": {
                "name": "Host",
                "total_upload": "Total upload",
                "total_download": "Total download",
                "total": "Sum of upload and download"
        }
},
]
  • On failed request:
    • HTTP Code: 500 Internal Server Error
    • Response Body:
{"error": "No data available"}

Delete entries

This section covers all endpoints related to deleting entries from the database. The DELETE operation is performed on the "active_process" table of the database, but since the "process_data", "protocol_data" and "host_data" foreign keys are set to cascade on delete, all related entries on these tables are deleted as well. When a DELETE operation is performed, a VACUUM operation is also performed to reduce the database size on disk.

DELETE

/delete

  • Deletes all entries from the tables active_process, process_data, protocol_data and host_data. A time frame can be used to filter the applications.
  • Query Parameters:
    • initialDate: number -> Initial time in the timeframe, in Unix timestamp in millis
    • endDate: number -> Final time in the timeframe, in Unix timestamp in millis
  • On successful request:
    • HTTP Code: 200 OK
    • Response Body:
{"message": "Entries deleted sucessfully"}
  • On failed request:
    • HTTP Code: 500 Internal Server Error
    • Response Body:
{"error": "SQL Error Message"}
Clone this wiki locally