sio-2425/delivery3/features.adoc

== Features

The features of the project are the ones present in the course project description, but with an extra feature, the possibility to reset the database of the server. This was shown to be useful for testing purposes, but it should be disabled/deleted in a production environment.


The API has a list of endpoints that require different permission levels to access. Mainly, it's divided into 3 categories:

* <<_anonymous_endpoints,Anonymous>>: No authentication required.
* <<_authenticated_endpoints,Authenticated>>: Authentication required.
* <<_authorized_endpoints,Authorized>>: Authentication and permissions required.

[[_anonymous_endpoints]]
=== Anonymous Endpoints

[cols="1,1,1,1", options="header"]
|===
| Endpoint | Required headers | Required payload fields | Optional payload parameters

a| `GET /` → Returns a ping message.
| N/A
| N/A
| N/A

a| `POST /reset` → Resets the database and deletes all data.
a| * `Content-Type: application/json`
a| * `password`: The reset password. *Note: The reset password is `123` (very secure!).*
| N/A

a| `GET /org/list` → Returns a list of all organizations.
| N/A
| N/A
| N/A

a| `POST /org/create` → Creates a new organization.
a| * `Content-Type: application/octet-stream`
a|
* `name`: Organization name.
* `username`: Manager username.
* `full_name`: Manager full name.
* `email`: Manager email.
* `public_key`: Manager public key.
| N/A

a| `GET /file/get/<file_handle>/content` → Downloads the file content.
| N/A
| N/A
| N/A

.2+a| `POST /user/login` → Logs in a user.
a| * `Content-Type: application/json`
a| * `org`: Organization name.
* `username`: User username.
| N/A

a| * `Content-Type: application/octet-stream`
* `Authorization: token`
a| * `signature`: Signature of the challenge using the private key.
| N/A

|===

[[_authenticated_endpoints]]
=== Authenticated Endpoints

[cols="1,1,1,1", options="header", source]
|===
| Endpoint | Required headers | Required payload fields | Optional payload parameters

a| `GET /user/list` → Returns a list of all users
a| * `Content-Type: application/octet-stream`
* `Authorization: token`
| N/A
a| * `username`: Filter by username.

a| `GET /user/<username>/roles` → Returns a list of all roles of a user.
a| * `Authorization: token`
| N/A
| N/A

a| `GET /file/list` → Returns a list of all files.
a| * `Content-Type: application/octet-stream`
* `Authorization: token`
| N/A
a| * `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)

a| `POST /user/logout` → Logs out a user.
a| * `Authorization: token`
| N/A
| N/A

a| `POST /role/session/assume/<role>` → Assumes a role in the session.
a| * `Authorization: token`
| N/A
| N/A

a| `POST /role/session/drop/<role>` → Drops a role from the session.
a| * `Authorization: token`
| N/A
| N/A

a| `GET /role/session/list` → Lists the roles for the session.
a| * `Authorization: token`
| N/A
| N/A

a| `GET /role/<role>/list/users` → Lists the users for a role.
a| * `Authorization: token`
| N/A
| N/A

a| `GET /role/<role>/list/perms` → Lists the permissions for a role.
a| * `Authorization: token`
| N/A
| N/A

a| `GET /role/perm/<perm>/roles`: → Lists the roles with a permission.
a| * `Authorization: token`
| N/A
| N/A

|===

[[_authorized_endpoints]]
=== Authorized Endpoints

[cols="1,1,1,1", options="header", source]
|===
| Endpoint | Required headers | Required payload fields | Required permission

| `POST /user/create` → Creates a new user.
a| * `Content-Type: application/octet-stream`
* `Authorization: token`
a| * `username`: User's username.
* `name`: User's name.
* `email`: User's email.
* `public_key`: User's public key.
| SUBJECT_NEW

a| `POST /user/<username>/suspend` → Suspends a user.
a| * `Authorization: token`
| N/A
| SUBJECT_DOWN

a| `POST /user/<username>/activate` → Activates a user.
a| `Authorization: token`
| N/A
| SUBJECT_UP

a| `POST /file/upload/metadata` → Uploads a file's metadata.
a| * `Content-Type: application/octet-stream`
* `Authorization: token`
a| * `document_name`: Document name.
* `key`: Document key.
* `alg`: Document algorithm.
| DOC_NEW

a| `POST /file/upload/content` → Uploads a file's content.
a| * `Authorization: token`
* `Content-Type: multipart/form-data`
a| * file's content as request data
| DOC_NEW

a| `GET /file/get/<document_handle>/metadata` → Downloads a file's metadata.
a| * `Authorization: token`
| N/A
| DOC_READ

a| `POST /file/delete/<document_handle>` → Deletes a file.
a| * `Authorization: token`
| N/A
| DOC_DELETE

a| `POST /file/acl` → Updates the ACL of a file.
a| * `Content-Type: application/octet-stream`
* `Authorization: token`
a| * `document_handle`: Document handle.
* `role`: Role name.
* `perm`: Permission name.
* `operation`: `add` \| `remove`. (One of the following: add, remove)
| DOC_ACL

a| `POST /role/create` → Creates a new role.
a| * `Content-Type: application/octet-stream`
* `Authorization: token`
a| * `role`: Role name.
| ROLE_NEW

a| `POST /role/<role>/suspend` → Suspends a role.
a| * `Authorization: token`
| N/A
| ROLE_DOWN

a| `POST /role/<role>/activate` → Activates a role
a| * `Authorization: token`
| N/A
| ROLE_UP

a| `POST /role/<role>/user/add/<username>` → Adds a user to a role.
a| * `Authorization: token`
| N/A
| ROLE_MOD

a| `POST /role/<role>/user/remove/<username>` → Removes a user from a role.
a| * `Authorization: token`
| N/A
| ROLE_MOD

a| `POST /role/<role>/perm/add/<perm>` → Adds a permission to a role.
a| * `Authorization: token`
| N/A
| ROLE_MOD

a| `POST /role/<role>/perm/remove/<perm>` → Removes a permission from a role.
a| * `Authorization: token`
| N/A
| ROLE_MOD

|===