fix: API documentation for Task Result type #524

kairoaraujo · 2024-01-30T18:31:01Z

Description

Fix documentation about the type of task result in the
/api/v1/tasks.

The type was moved to Dict[str, Any]

It adds more consistency on task result in the API.
Verifying the message and status and error (in case of FAILURE)

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality not to work as expected)

Additional requirements

Tests have been added for the bug fix or new feature
Docs have been added for the bug fix or new feature

Code of Conduct

By submitting this PR, you agree to follow our Code of Conduct.

I agree to follow this project's Code of Conduct

codecov · 2024-01-31T05:32:48Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (1464ad7) 99.01% compared to head (ddd900a) 99.00%.

❗ Current head ddd900a differs from pull request most recent head c55f15c. Consider uploading reports for the commit c55f15c to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #524      +/-   ##
==========================================
- Coverage   99.01%   99.00%   -0.01%     
==========================================
  Files          14       14              
  Lines         607      605       -2     
==========================================
- Hits          601      599       -2     
  Misses          6        6

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

kairoaraujo · 2024-02-01T08:58:33Z

I'm including #528 in this PR in another commit as it is related to this PR.

repository_service_tuf_api/tasks.py

lukpueh · 2024-02-02T11:12:50Z

Summarising a chat with Kairo:

API results should be designed with the user in mind.
Case-handling of different results should be as easy as possible.
The user shouldn't need parse strings to make decisions.
If the user generally doesn't care for the difference between certain response types, or doesn't handle them differently, it might be okay to summarise those response type.
For now we stick to the existing response types coming and forward them mostly as they come from celery/worker.

Maybe we can consider some simplifications, if they don't disrupt existing clients:

Exclude redundant status field from task result.
Only mandate task results with message field for SUCCESS, ERROR, FAILURE state responses, and do not add them if they are missing in any of the other state responses.
Consolidate message and error fields for ERROR and FAILURE.
For ERROR the message could be a combination of what's currently in both fields, and error could be omitted.
For FAILURE the message could be the exception message, and error could be omitted or show the exception type.

Fix documentation about the type of task result in the `/api/v1/tasks`. The type was moved to `Dict[str, Any]` It adds more consistency on task result in the API. Verifying the `message` and `status` and `error` (in case of FAILURE) Signed-off-by: Kairo Araujo <kairo.araujo@testifysec.com>

Include descriptions in the Model (Swagger) documentation. Signed-off-by: Kairo Araujo <kairo.araujo@testifysec.com>

Signed-off-by: Kairo Araujo <kairo.araujo@testifysec.com>

lukpueh

I think the changes are okay. Feel free to address the two inline comments or not.

Regarding our chat:

Only mandate task results with message field for SUCCESS, ERROR, FAILURE state responses, and do not add them if they are missing in any of the other state responses.

Consolidate message and error fields for ERROR and FAILURE.

For ERROR the message could be a combination of what's currently in both fields, and error could be omitted.

For FAILURE the message could be the exception message, and error could be omitted or show the exception type.

Did you consider any of those? I suppose they are improvements that should be done in the worker first.

lukpueh · 2024-02-07T16:42:33Z

repository_service_tuf_api/tasks.py

-        task_result = {"message": str(task.result)}
-    elif task_state == TaskState.SUCCESS and not task_result.get(
+        task_result = {
+            "message": f"Task failure: {str(task.result)}",


nit: IMO you can omit "Task failure: ". The info is redundant with the state.

lukpueh · 2024-02-07T16:44:34Z

docs/swagger.json

+                    "error": {
+                        "type": "string",
+                        "title": "Error",
+                        "description": "If the task status result is `False` shows an error message"


Is this API user facing documentation? They don't know about task status, right?

kairoaraujo · 2024-02-07T17:14:58Z

Did you consider any of those? I suppose they are improvements that should be done in the worker first.

Yes, most of them are how the RSTUF Worker sends the task result, not in the API.
We should file issues to do there, as a polishing result.

I noticed also that removing status from result is a breaking change for the CLI :)
I mean, we will need changes there.

lukpueh · 2024-02-07T17:23:30Z

I noticed also that removing status from result is a breaking change for the CLI :)
I mean, we will need changes there.

Damn. I guess it's also okay to leave it, and ignoring it in the cli first?

kairoaraujo · 2024-02-07T17:36:02Z

Damn. I guess it's also okay to leave it, and ignoring it in the cli first?

Yes, I will revert it and file issues so we can do it without breaking operability.

Signed-off-by: Kairo Araujo <kairo.araujo@testifysec.com>

kairoaraujo · 2024-02-09T10:05:06Z

I opened the following issues:

Task: Simplify the task result checks in CLI repository-service-tuf-cli#508
Task: Simplify the task result checks in Functional Tests repository-service-tuf#622
Task: Remove the status from result in the /api/v1/tasks response body #537
Task: Improve the task result by making the result message and error simpler repository-service-tuf-worker#454

kairoaraujo force-pushed the fix_documentation_api branch 2 times, most recently from 99385c2 to db11317 Compare January 31, 2024 05:30

kairoaraujo force-pushed the fix_documentation_api branch 4 times, most recently from 5e9f876 to 393e7bd Compare January 31, 2024 10:21

kairoaraujo self-assigned this Feb 1, 2024

lukpueh reviewed Feb 2, 2024

View reviewed changes

repository_service_tuf_api/tasks.py Outdated Show resolved Hide resolved

kairoaraujo added 2 commits February 7, 2024 11:42

docs: Include descriptions in the Swagger (Model)

cb5bf33

Include descriptions in the Model (Swagger) documentation. Signed-off-by: Kairo Araujo <kairo.araujo@testifysec.com>

kairoaraujo force-pushed the fix_documentation_api branch 2 times, most recently from 996d49b to edbd082 Compare February 7, 2024 11:02

kairoaraujo requested a review from lukpueh February 7, 2024 11:03

kairoaraujo force-pushed the fix_documentation_api branch from edbd082 to 8dbd831 Compare February 7, 2024 12:16

fixup! fix: API docs Task and improve consistency

ddd900a

Signed-off-by: Kairo Araujo <kairo.araujo@testifysec.com>

kairoaraujo force-pushed the fix_documentation_api branch from 8dbd831 to ddd900a Compare February 7, 2024 12:33

lukpueh approved these changes Feb 7, 2024

View reviewed changes

fixup! fixup! fix: API docs Task and improve consistency

c55f15c

Signed-off-by: Kairo Araujo <kairo.araujo@testifysec.com>

kairoaraujo force-pushed the fix_documentation_api branch from 92a8408 to c55f15c Compare February 7, 2024 17:55

kairoaraujo mentioned this pull request Feb 9, 2024

Task: Improve the task result by making the result message and error simpler repository-service-tuf/repository-service-tuf-worker#454

Open

1 task

lukpueh approved these changes Feb 9, 2024

View reviewed changes

kairoaraujo merged commit 50a1de0 into repository-service-tuf:main Feb 9, 2024
5 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: API documentation for Task Result type #524

fix: API documentation for Task Result type #524

kairoaraujo commented Jan 30, 2024 •

edited

Loading

codecov bot commented Jan 31, 2024 •

edited

Loading

kairoaraujo commented Feb 1, 2024

lukpueh commented Feb 2, 2024

lukpueh left a comment

lukpueh Feb 7, 2024

lukpueh Feb 7, 2024

kairoaraujo commented Feb 7, 2024

lukpueh commented Feb 7, 2024

kairoaraujo commented Feb 7, 2024

kairoaraujo commented Feb 9, 2024

fix: API documentation for Task Result type #524

fix: API documentation for Task Result type #524

Conversation

kairoaraujo commented Jan 30, 2024 • edited Loading

Description

Types of changes

Additional requirements

Code of Conduct

codecov bot commented Jan 31, 2024 • edited Loading

Codecov Report

kairoaraujo commented Feb 1, 2024

lukpueh commented Feb 2, 2024

lukpueh left a comment

Choose a reason for hiding this comment

lukpueh Feb 7, 2024

Choose a reason for hiding this comment

lukpueh Feb 7, 2024

Choose a reason for hiding this comment

kairoaraujo commented Feb 7, 2024

lukpueh commented Feb 7, 2024

kairoaraujo commented Feb 7, 2024

kairoaraujo commented Feb 9, 2024

kairoaraujo commented Jan 30, 2024 •

edited

Loading

codecov bot commented Jan 31, 2024 •

edited

Loading