Skip to content

docs: add tasks documentation #36

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
goncalorazevedo merged 1 commit into from
Sep 7, 2025
Merged

docs: add tasks documentation #36

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
157 changes: 141 additions & 16 deletions docs/usage-guide/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ Members
----

``GET /members``
~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~
**Description**
Retrieve a list of all registered members.

Expand All @@ -59,7 +59,7 @@ Members
----

``GET /members/<username>``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Description**
Retrieve member by username.

Expand All @@ -72,7 +72,7 @@ Members
----

``PUT /members/<username>``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Description**
Update an existing member’s information by their username.

Expand Down Expand Up @@ -122,7 +122,7 @@ Members
----

``GET /members/<username>/image``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Description**
Retrieve the profile image of a member by their username.

Expand All @@ -135,7 +135,7 @@ Members
----

``POST /members/<username>/image``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Description**
Update the profile image of a member by their username.

Expand All @@ -156,7 +156,7 @@ Members
----

``GET /members/<username>/participations/``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Description**
Get list of member's participations by username.

Expand Down Expand Up @@ -214,7 +214,7 @@ Projects
----

``GET /projects``
~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~
**Description**
Retrieve a list of all projects.

Expand All @@ -226,7 +226,7 @@ Projects
----

``GET /projects/<slug>``
~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Description**
Get a project by slug.

Expand Down Expand Up @@ -284,7 +284,7 @@ Projects
----

``GET /projects/<slug>/image``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Description**
Retrieve the profile image of a member by their username.

Expand Down Expand Up @@ -362,7 +362,7 @@ Projects


``GET /projects/<slug>/participations/<username>``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Description**
Retrieve details about a specific member’s participation in a project, identified by project slug and member username.

Expand All @@ -372,9 +372,134 @@ Projects
**Response format**
A participation object.

----

Tasks
------

``POST /projects/<slug>/tasks``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Description**
Create a new task for a member participating in a project.

**Request format**

.. code-block:: json

{
"point_type": "pj", // required, enum: ["pj", "pcc"]
"points": 1, // required, int
"description": "Fix login issue", // optional, string
"finished_at": null, // optional, string, ISO 8601 date (YYYY-MM-DD)
"username": "alice" // required, string, 3-32 chars, alphanumeric only
}

**Response format**
Returns the created task object, as follows:

.. code-block:: json

{
"id": 1,
"point_type": "pj",
"points": 1,
"description": "Fix login issue",
"finished_at": null,
"username": "alice",
"project_name": "HS API"
}

----

``GET /tasks``
~~~~~~~~~~~~~~~~~~
**Description**
Retrieve a list of all tasks across all projects.

**Request format**
No request body required.

**Response format**
List of task objects.

----

``GET /tasks/<task_id>``
~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Description**
Retrieve a task by its ID.

**Request format**
No request body required.

**Response format**
The task object with given ID.

``PUT /tasks/<task_id>``
~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Description**
Update an existing task by its ID.

**Request format**
Updated task object.

.. code-block:: json

{
"point_type": "pj", // optional, enum: ["pj", "pcc"]
"points": 10, // optional, int
"description": "Implement dashboard", // optional, string
"finished_at": "2025-08-20" // optional, string, ISO 8601 date (YYYY-MM-DD)
}

**Response format**
Updated task object.

----

``DELETE /tasks/<task_id>``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Description**
Delete a task by its ID.

**Request format**
No request body required.

**Response format**

.. code-block:: json

{
"description": "Task deleted successfully",
"id": 123
}

----

``GET /projects/<slug>/tasks``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Description**
Retrieve all tasks associated with a specific project.

**Request format**
No request body required.

**Response format**
List of tasks belonging to the given project.

----

``GET /members/<username>/tasks``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Description**
Retrieve all tasks assigned to a specific member across all projects.

**Request format**
No request body required.

**Response format**
List of tasks done by given member.

Authentication
----------------

Expand All @@ -383,7 +508,7 @@ server side and a cookie is sent back with the session ID to identify the client

You can initiate a session with a traditional login password or through Fenix.

``POST /login```
``POST /login``
~~~~~~~~~~~~~~~~~~~
**Description**
Login with username and password
Expand All @@ -406,12 +531,12 @@ You can initiate a session with a traditional login password or through Fenix.

----

``GET /fenix-login```
~~~~~~~~~~~~~~~~~~~
The Fenix authentication is made using OAuth 2.0 and the ``/fenix-login`` endpoint starts the OAuth Flow.
``GET /fenix-login``
~~~~~~~~~~~~~~~~~~~~~~~
The Fenix authentication is made using OAuth 2.0 and the ``/fenix-login`` endpoint starts the OAuth Flow. Provide a ``?next=`` query parameter with the
URL to where the user should be redirected to on the frontend once the flow is completed.

Once the flow is complete and if the user's IST ID is also present in the database, then the authentication is complete and the
the same response as ``POST /login`` is sent.
When the flow is complete and, if the user's IST ID is also present in the database, then the authentication is complete and the user is redirected to the ``next`` param provided. The user is redirected with the following query parameters: ``?login=success&username=<username>`` or simply ``?login=fail`` if the authentication fails.

----

Expand Down