sio-2425/delivery2/README.md

# SIO 2024 - Projeto 1

## Group

- João Pedro Fonseca Bastos - 113470 - joaop.bastos@ua.pt
- Rúben da Loura Cristóvão Gomes - 113435 - rlcg@ua.pt
- Tiago Rocha Garcia - 114184 - tiago.rgarcia@ua.pt

## API

### Usage

The API run as a RESTful service using the flask framework. A test API is hosted on the following URL: `https://sio.tiagorg.pt`.

To run, first create the virtual environment and install the dependencies:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Then, run the API:

```bash
flask run --port <port>
```

*Note: The API is hosted on port 5000 by default.*
*Note: You can also run the API in debug mode with the flag `--debug`.*

### Endpoints

The API has a list of endpoints that require different permission levels to access.

Mainly, it's divided into 3 categories:

- Anonymous: No authentication required.
- Authenticated: Authentication required.
- Authorized: Authentication and permissions required.

#### Anonymous Endpoints

- `GET /`: Returns a ping message.
- `POST /reset`: Resets the database and deletes all data.
  - Required headers:
    - `Content-Type: application/json`
  - Required payload fields:
    - `password`: The reset password. *Note: The reset password is `123`.*
- `GET /org/list`: Returns a list of organizations.
- `POST /org/create`: Creates a new organization.
  - Required headers:
    - `Content-Type: application/json`
  - Required payload fields:
    - `name`: Organization name.
    - `username`: Manager username.
    - `full_name`: Manager full name.
    - `email`: Manager email.
    - `public_key`: Manager public key.
- `GET /file/get/<file_handle>/content`: Downloads the file content.
- `POST /user/login`: Logs in a user.
  - Required headers:
    - `Content-Type: application/json`
  - Required payload fields:
    - `org`: Organization name.
    - `username`: User username.
    - `password`: User password.
    - `credentials_file`: User credentials file.

#### Authenticated Endpoints

- `GET /user/list`: Returns a list of users.
  - Required headers:
    - `Authorization: token`
  - Optional payload parameters:
    - `username`: Filter by username.
- `GET /user/<username>/roles`: Returns a list of roles for a user.
  - Required headers:
    - `Authorization: token`
- `GET /file/list`: Returns a list of files.
  - Required headers:
    - `Authorization: token`
  - Optional payload parameters:
    - `username`: Filter by username.
    - `datetime`: Filter by datetime. The datetime filter has the following fields:
      - `value`: Epoch time in seconds.
      - `relation`: `ot` | `eq` | `nt`. (One of the following: older than, equal to, newer than)
- `POST /user/logout`: Logs out a user.
  - Required headers:
    - `Authorization: token`
- `POST /role/session/assume`: Assumes a role in the session.
  - Required headers:
    - `Authorization: token`
  - Required payload fields:
    - `role`: Role name.
- `POST /role/session/drop`: Drops a role from the session.
  - Required headers:
    - `Authorization: token`
  - Required payload fields:
    - `role`: Role name.
- `GET /role/session/list`: Lists the roles for the session.
  - Required headers:
    - `Authorization: token`
- `GET /role/<role>/list/users`: Lists the users for a role.
  - Required headers:
    - `Authorization: token`
- `GET /role/<role>/list/perms`: Lists the permissions for a role.
  - Required headers:
    - `Authorization: token`
- `GET /role/perm/<perm>/roles`: Lists the roles with a permission.
  - Required headers:
    - `Authorization: token`

#### Authorized Endpoints

- `POST /user/create`: Creates a new user.
  - Required headers:
    - `Authorization: token`
    - `Content-Type: application/json`
  - Required payload fields:
    - `username`: User username.
    - `name`: User name.
    - `email`: User email.
    - `public_key`: User public key.
- `POST /user/<username>/suspend`: Suspends a user.
  - Required headers:
    - `Authorization: token`
- `POST /user/<username>/activate`: Activates a user.
  - Required headers:
    - `Authorization: token`
- `POST /file/upload/metadata`: Uploads file metadata.
  - Required headers:
    - `Authorization: token`
    - `Content-Type: application/json`
  - Required payload fields:
    - `document_name`: Document name.
    - `key`: Document key.
    - `alg`: Document algorithm.
    - `nonce`: Document nonce.
- `POST /file/upload/content`: Uploads file content, content-type must be `multipart/form-data`.
  - Required headers:
    - `Authorization: token`
    - `Content-Type: multipart/form-data`
  - Required payload fields:
    - `content`: Document content.
- `GET /file/get/<document_handle>/metadata`: Downloads file metadata.
  - Required headers:
    - `Authorization: token`
- `POST /file/delete/<document_handle>`: Deletes a file.
  - Required headers:
    - `Authorization: token
- `POST /role/create`: Creates a new role.
  - Required headers:
    - `Authorization: token`
  - Required payload fields:
    - `role`: Role name.
- `POST /role/<role>/suspend`: Suspends a role.
  - Required headers:
    - `Authorization: token`
- `POST /role/<role>/activate`: Activates a role.
  - Required headers:
    - `Authorization: token`
- `POST /role/<role>/user/add/<username>`: Adds a user to a role.
  - Required headers:
    - `Authorization: token`
- `POST /role/<role>/user/remove/<username>`: Removes a user from a role.
  - Required headers:
    - `Authorization: token`
- `POST /role/<role>/perm/add/<perm>`: Adds a permission to a role.
  - Required headers:
    - `Authorization: token`
- `POST /role/<role>/perm/remove/<perm>`: Removes a permission from a role.
  - Required headers:
    - `Authorization: token`