Add API description

Signed-off-by: Tiago Garcia <tiago.rgarcia@ua.pt>

delivery1/README.md

@@ -1 +1,126 @@
+# 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 /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`
+
+#### 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

delivery1/server/tests/user_management.http

@@ -36,9 +36,9 @@ GET http://localhost:5000/org/list
 ### Create a new user
 POST http://localhost:5000/user/create
 Content-Type: application/json
+Authorization: {{token}}
 
 {
-  "session_file": "{\"token\":\"{{token}}\"}",
   "username": "newuser",
   "full_name": "Full Name",
   "email": "newuser@mail.com",
@@ -48,33 +48,29 @@ Content-Type: application/json
 ### List users
 GET http://localhost:5000/user/list
 Content-Type: application/json
+Authorization: {{token}}
 
-{
+{}
-  "session_file": "{\"token\":\"{{token}}\"}"
-}
 
 ### Suspend user
 POST http://localhost:5000/user/suspend
 Content-Type: application/json
+Authorization: {{token}}
 
 {
-  "session_file": "{\"token\":\"{{token}}\"}",
   "username": "newuser"
 }
 
 ### Activate user
 POST http://localhost:5000/user/activate
 Content-Type: application/json
+Authorization: {{token}}
 
 {
-  "session_file": "{\"token\":\"{{token}}\"}",
   "username": "newuser"
 }
 
 ### Logout
 POST http://localhost:5000/user/logout
 Content-Type: application/json
-
+Authorization: {{token}}
-{
-  "session_file": "{\"token\":\"{{token}}\"}"
-}