sio-2425/delivery2

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:

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

Then, run the API:

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 /file/acl: Updates the ACL for a file.
  • Required headers:
    • Authorization: token
  • Required payload fields:
    • document_handle: Document handle.
    • role: Role name.
    • perm: Permission name.
    • operation: add | remove. (One of the following: add, remove)
• 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