readme.md 5.07 KB
Newer Older
Siebers, Michael's avatar
Siebers, Michael committed
1
# Dare2Del Demonstrator – WebAPI
Sebastian Seufert's avatar
Sebastian Seufert committed
2

Siebers, Michael's avatar
Siebers, Michael committed
3 4
The Dare2Del Demonstrator identifies irrelevant files in the user's file system and suggests to delete them. This project provides the required reasoning facilities as Service over HTTP. This component holds all parts required to answer whether some file is irrelevant and to explain why this is the case. 
Basically, the core logic is encapsulated into a web-based API that receives and responds JSON objects:
Sebastian Seufert's avatar
Sebastian Seufert committed
5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20


```mermaid
sequenceDiagram
    participant Client
    
    participant API
    Client->>API: HTTP Request
    API-->>Theory: Query
    loop Rules & Learning
        Theory-->>Theory: Irrelevancy / Explanation
    end
    Theory-->>API: Query Results
    API->>Client: HTTP Response
```

Siebers, Michael's avatar
Siebers, Michael committed
21
## Running the server
Siebers, Michael's avatar
Siebers, Michael committed
22 23 24 25
The WebAPI server is implemented as [SWI-Prolog](https://www.swi-prolog.org/) program using several libraries. It requires SWI-Prolog version 8.2.2 or above to run. 
The server may operate in two different modes: in _interactive_ mode or as a unix _deamon_.
In the _interactive_ mode the server is running as background _thread_ within the interactive prolog interpreter. This mode allows to inspect and debug the running of the server as well as to apply changes on the fly.
On the other hand, the server runs as background _process_ of the operating system in _daemon_ mode. This mode is intended for production use.
Siebers, Michael's avatar
Siebers, Michael committed
26

Siebers, Michael's avatar
Siebers, Michael committed
27
Before starting the server, you have to clone the git repository.
Siebers, Michael's avatar
Siebers, Michael committed
28 29 30 31 32 33

```bash
    git clone git@gitlab.rz.uni-bamberg.de:cogsys/dare2del/demonstrator.git demonstrator-webapi
    cd demonstrator-webapi
```

Siebers, Michael's avatar
Siebers, Michael committed
34 35
### Interactive Mode
The interactive mode is started using the `run.pl` script. You may supply a custom port that the server will listen on (default is 4444).
Siebers, Michael's avatar
Siebers, Michael committed
36 37 38 39 40 41

```bash
    swipl run.pl
    swipl run.pl --port 4444
```

42
After some informational messages (starting with `%`) you will see the interactive prolog interpreter. Then the server is running and accepting requests at localhost:PORT as given in the last informational message.
Siebers, Michael's avatar
Siebers, Michael committed
43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71

```
    % Loading explanation templates from file irrelevance_templates:
    %     file/1
    %     abs_path/2
    %     file_size/2
    %     directory/1
    %     in_directory/2
    %     in_directory_recursive/2
    %     in_directory_recursive/2
    %     item_name/2
    %     creation_time/2
    %     change_time/2
    %     modification_time/2
    %     access_time/2
    %     newer/2
    %     same_directory/2
    % Started server at http://localhost:4444/

    Welcome to SWI-Prolog (threaded, 64 bits, version 8.2.2)
    SWI-Prolog comes with ABSOLUTELY NO WARRANTY. This is free software.
    Please run ?- license. for legal details.

    For online help and background, visit https://www.swi-prolog.org
    For built-in help, use ?- help(Topic). or ?- apropos(Word).

    ?-
```

Siebers, Michael's avatar
Siebers, Michael committed
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117
You may freely use the Prolog interpreter while the server is running.
The server access log is stored in the file `log.txt` in the working directory. To stop the server enter `server_stop.`

### Daemon Mode
> Please note that the _daemon_ mode requires a unix-like operation system to run!

The server is started and stopped in _daemon_ mode using the `daemon.pl` script. As in _interactive_ mode, the server listens on port 4444 per default. This may be configured using the `--port` command line switch.

```bash
    swipl daemon.pl
    swipl daemon.pl --port 4444
```

After some informational messages (starting with `%`), control is given back to the calling process (the command line) as soon as the server has started successfully. Further output is discarded. (_This includes the informational message that the server has started up successfully._)

```
    % Loading explanation templates from file irrelevance_templates:
    %     file/1
    %     abs_path/2
    %     file_size/2
    %     directory/1
    %     in_directory/2
    %     in_directory_recursive/2
    %     in_directory_recursive/2
    %     item_name/2
    %     creation_time/2
    %     change_time/2
    %     modification_time/2
    %     access_time/2
    %     newer/2
    %     same_directory/2
```

The server access log is stored in the file `log.txt` in the working directory.
You may use the `--outfile` command line switch to capture the Prolog output after successful server start.

```bash
    swipl daemon.pl --outfile daemon.out
```

The daemon is stopped using the `--shutdown` command line switch.

```bash
    swipl daemon.pl --shutdown
```

Siebers, Michael's avatar
Siebers, Michael committed
118 119

## Documentation
120
[^local]: Links to localhost in section _Documentation_ assume that you started the server without explicit port option. If you started the server under another port, please replace `4444` accordingly.
Sebastian Seufert's avatar
Sebastian Seufert committed
121

Siebers, Michael's avatar
Siebers, Michael committed
122
The Dare2Del Demonstrator WebAPI component serves its own documentation. Unless turned off (see [Admin Guide](http://localhost:4444/doc/admin_guide.html)[^local]), the documentation may be accessed under [/doc](http://localhost:4444/doc)[^local]. Notably the following documents are available:
Sebastian Seufert's avatar
Sebastian Seufert committed
123

Siebers, Michael's avatar
Siebers, Michael committed
124
1. A [detailed description of the API endpoints](http://localhost:4444/doc/api_endpoints.html)[^local]
125
1. A [file-by-file documentation of Prolog predicates](http://localhost:4444/doc/pldoc/doc/_API_/index.html)[^local]
Sebastian Seufert's avatar
moving  
Sebastian Seufert committed
126

Siebers, Michael's avatar
Siebers, Michael committed
127
---