From 3f2de12971a5608002930c2f6f6f948f335dacd4 Mon Sep 17 00:00:00 2001 From: minusunil Date: Sun, 28 Jul 2024 19:23:03 +1000 Subject: [PATCH 1/5] API documentation for admin,tasks,submission,tii_actions --- src/content/docs/backend/API/admin.md | 179 ++++++++++++- src/content/docs/backend/API/submission.md | 161 +++++++++++- src/content/docs/backend/API/tasks.md | 273 +++++++++++++++++++- src/content/docs/backend/API/tii_actions.md | 90 ++++++- 4 files changed, 685 insertions(+), 18 deletions(-) diff --git a/src/content/docs/backend/API/admin.md b/src/content/docs/backend/API/admin.md index d4c830c..84b929e 100644 --- a/src/content/docs/backend/API/admin.md +++ b/src/content/docs/backend/API/admin.md @@ -2,15 +2,190 @@ title: Doubtfire API Documentation --- -# API: Admin +# API: Admin + admin : Operations about admin This markdown document provides detailed documentation for the "admin" API endpoints, including their URLs, methods, parameters (if any), responses, and example requests using curl This "admin" API has the following operations. + - **PUT**: /api/admin/overseer_images/{id}/pull_image - **GET**: /api/admin/overseer_images - **POST**: /api/admin/overseer_images - **DELETE**: /api/admin/overseer_images/{id} - **PUT**: /api/admin/overseer_images/{id} -## Detail of Operations related to admin. \ No newline at end of file +## Detail of Operations related to admin. + +### PUT: Pull Overseer Image + +PUT /api/admin/overseer_images/{id}/pull_image + +- URL: `/api/admin/overseer_images/{id}/pull_image` +- Method: `PUT` +- Parameters: + | Parameter | Description |Parameter Type| Data Type|Mandatory| + |---------------------|-----------------|------------|------------|---| + |id |Overseer image ID| path | integer|Yes| + |Username | User username | header | string | Yes | + |Auth_Token | Authentication token | header | string |Yes| + +- Response: + `200 OK` + +- Example Request: + ```bash + curl -X PUT --header 'Accept: application/json' --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' 'http://localhost:3000/api/admin/overseer_images/1/pull_image' + ``` +- Response body: + ```json + { + "id": 1, + "name": "Example Image", + "tag": "example/tag", + "status": "pulled" + } + ``` + +--- + +### GET: Retrieve All Overseer Images + +GET /api/admin/overseer_images + +- URL: `/api/admin/overseer_images` +- Method: `GET` +- Parameters: + | Parameter | Description |Parameter Type| Data Type|Mandatory| + |---------------------|-----------------|------------|------------|---| + |Username | User username | header | string | Yes | + |Auth_Token | Authentication token | header | string |Yes| + +- Response: + `200 OK` + +- Example Request: + ```bash + curl -X PUT --header 'Accept: application/json' --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' 'http://localhost:3000/api/admin/overseer_images' + ``` +- Response Body: + ```json + [ + { + "id": 1, + "name": "Example Image", + "tag": "example/tag" + }, + { + "id": 2, + "name": "Another Image", + "tag": "another/tag" + } + ] + ``` + +--- + +### POST: Add an Overseer Image + +POST /api/admin/overseer_images + +- URL: `/api/admin/overseer_images` +- Method: `POST` +- Parameters: + | Parameter | Description | Parameter Type | Data Type | Mandatory | + |-----------------------|-------------------------------------------|----------------|-----------|-----------| + | overseer_image | The overseer image object | body | hash | Yes | + | overseer_image.name | The name to display for this image | body | string | Yes | + | overseer_image.tag | The tag used to retrieve from container repo | body | string | Yes | + | Username | User username | header | string | Yes | + | Auth_Token | Authentication token | header | string | Yes | + +- Response: + `201` + +- Example Request: + ```bash + curl -X POST --header 'Content-Type: application/json' --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n'-d '{ + "overseer_image": { + "name": "Example Image", + "tag": "example/tag" + } + }' 'http://localhost:3000/api/admin/overseer_images' + ``` +- Response Body: + ```json + { + "id": 1, + "name": "Example Image", + "tag": "example/tag" + } + ``` + +--- + +### DELETE: Delete an Overseer Image + +DELETE /api/admin/overseer_images/{id} + +- URL: `/api/admin/overseer_images/{id}` +- Method: `DELETE` +- Parameters: + + | Parameter | Description | Parameter Type | Data Type | Mandatory | + | ---------- | -------------------- | -------------- | --------- | --------- | + | id | Overseer image ID | path | integer | Yes | + | Username | User username | header | string | Yes | + | Auth_Token | Authentication token | header | string | Yes | + +- Response: + + - `204` + +- Example Request: + ```bash + curl -X DELETE --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' 'http://localhost:3000/api/admin/overseer_images/1' + ``` +- Response Body: + `Overseer image deleted ` + +--- + +### PUT: Update an Overseer Image + +PUT /api/admin/overseer_images/{id} + +- URL: `/api/admin/overseer_images/{id}` +- Method: `PUT` +- Parameters: + + | Parameter | Description | Parameter Type | Data Type | Mandatory | + | ------------------- | -------------------------------------------- | -------------- | --------- | --------- | + | id | Overseer image ID | path | integer | Yes | + | overseer_image | The overseer image object | body | hash | Yes | + | overseer_image.name | The name to display for this image | body | string | No | + | overseer_image.tag | The tag used to retrieve from container repo | body | string | No | + | Username | User username | header | string | Yes | + | Auth_Token | Authentication token | header | string | Yes | + +- Response: + `200 OK` + +- Example Request: + ```bash + curl -X PUT --header 'Content-Type: application/json' --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' + -d '{ + "overseer_image": { + "name": "Updated Example Image", + "tag": "updated/tag" + } + }' 'http://localhost:3000/api/admin/overseer_images/1' + ``` +- Response Body: + ```json + { + "id": 1, + "name": "Updated Example Image", + "tag": "updated/tag" + } + ``` diff --git a/src/content/docs/backend/API/submission.md b/src/content/docs/backend/API/submission.md index 4e0be8a..ada8537 100644 --- a/src/content/docs/backend/API/submission.md +++ b/src/content/docs/backend/API/submission.md @@ -1,12 +1,11 @@ --- -title: Doubtfire API +title: Doubtfire API --- -# List of Doubtfire - # API: Submission + submission : Operations about submission -This markdown document provides detailed documentation for the "submission" API endpoints including their URLs, methods, parameters, responses, and example requests using curl. +This markdown document provides detailed documentation for the "submission" API endpoints including their URLs, methods, parameters, responses, and example requests using curl. This "submission" API has the following operations. @@ -14,7 +13,157 @@ This "submission" API has the following operations. - **POST**: /api/submission/assess - **DELETE**: /api/submission/project/{id}/portfolio - **GET**: /api/submission/project/{id}/portfolio -- **PUT**: /api/submission/project/{id}/portfolio +- **POST**: /api/submission/project/{id}/portfolio + +## Detail of Operations related to submission. + +### GET: Retrieve Submissions Ready to Mark + +GET /api/submission/assess + +- URL: `/api/submission/assess` +- Method: `GET` +- Parameters: + + | Parameter | Description | Parameter Type | Data Type | Mandatory | + | ---------- | ---------------------------------------------- | -------------- | --------- | --------- | + | unit_id | Unit ID to retrieve submissions for | query | integer | Yes | + | user_id | User ID to retrieve submissions for (optional) | query | integer | No | + | Username | User username | header | string | Yes | + | Auth_Token | Authentication token | header | string | Yes | + +- Response: + `200 OK` + +- Example Request: + ```bash + curl -X GET --header 'Accept: application/json' --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' 'http://localhost:3000/api/submission/assess?unit_id=1&user_id=2' + ``` +- Response Body: + This endpoint returns a zip file containing the tasks ready for marking. The response does not have a JSON body. + +--- + +### POST: Upload Submission Documents + +POST /api/submission/assess + +- URL: `/api/submission/assess` +- Method: `POST` +- Parameters: + + | Parameter | Description | Parameter Type | Data Type | Mandatory | + | ---------- | -------------------------------------------------- | -------------- | --------- | --------- | + | file | Batch file upload | body | file | Yes | + | unit_id | Unit ID to upload marked submissions to | body | integer | Yes | + | user_id | User ID to upload marked submissions to (optional) | body | integer | No | + | Username | User username | header | string | Yes | + | Auth_Token | Authentication token | header | string | Yes | + +- Response: + `201` + +- Example Request: + ```bash + curl -X POST --header 'Content-Type: multipart/form-data' --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' -F 'file=@path_to_your_file' -F 'unit_id=1' -F 'user_id=2' 'http://localhost:3000/api/submission/assess' + ``` +- Response Body: + ```json + { + "message": "Batch upload successful" + } + ``` + +--- + +### POST: Upload Portfolio Document + +POST /api/submission/project/{id}/portfolio + +- URL: `/api/submission/project/{id}/portfolio` +- Method: `POST` +- Parameters: + + | Parameter | Description | Parameter Type | Data Type | Mandatory | + | ---------- | --------------------------------------------------------- | -------------- | --------- | --------- | + | name | Name of the part being uploaded | body | string | Yes | + | kind | The kind of file being uploaded: document, code, or image | body | string | Yes | + | file0 | The file being uploaded | body | file | Yes | + | Username | User username | header | string | Yes | + | Auth_Token | Authentication token | header | string | Yes | + +- Response: + `201` + +- Example Request: + + ```bash + curl -X POST --header 'Content-Type: multipart/form-data' --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' -F 'name=Part 1' -F 'kind=document' -F 'file0=@path_to_your_file' 'http://localhost:3000/api/submission/project/1/portfolio' + ``` + +- Response Body: + ```json + { + "file_name": "Part 1", + "file_kind": "document", + "file_path": "path_to_file" + } + ``` + +--- + +### DELETE: Remove Portfolio Document + +DELETE /api/submission/project/{id}/portfolio + +- URL: `/api/submission/project/{id}/portfolio` +- Method: `DELETE` +- Parameters: + + | Parameter | Description | Parameter Type | Data Type | Mandatory | + | ---------- | ------------------------------------------------------------------- | -------------- | --------- | --------- | + | id | Project ID | path | integer | Yes | + | idx | The index of the file (optional) | query | integer | No | + | kind | The kind of file being removed: document, code, or image (optional) | query | string | No | + | name | Name of file to remove (optional) | query | string | No | + | Username | User username | header | string | Yes | + | Auth_Token | Authentication token | header | string | Yes | + +- Response: + `204` + +- Example Request: + ```bash + curl -X DELETE --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' 'http://localhost:3000/api/submission/project/1/portfolio?idx=0&kind=document&name=Part 1' + ``` +- Response Body: + `Portfolio deleted ` + +--- + +### GET: Retrieve Portfolio + +GET /api/submission/project/{id}/portfolio + +- URL: `/api/submission/project/{id}/portfolio` +- Method: `GET` +- Parameters: + + | Parameter | Description | Parameter Type | Data Type | Mandatory | + | ------------- | -------------------------------------------------------- | -------------- | --------- | --------- | + | id | Project ID | path | integer | Yes | + | as_attachment | Whether or not to download file as attachment (optional) | query | boolean | No | + | Username | User username | header | string | Yes | + | Auth_Token | Authentication token | header | string | Yes | + +- Response: + `200 OK` + +- Example Request: + ```bash + curl -X GET --header 'Accept: application/json' --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' 'http://localhost:3000/api/submission/project/1/portfolio?as_attachment=true' + ``` -## Detail of Operations related to submission. \ No newline at end of file +- Response Body: + This endpoint returns a PDF file of the portfolio. The response does not have a JSON body. diff --git a/src/content/docs/backend/API/tasks.md b/src/content/docs/backend/API/tasks.md index eeb92b4..9653a7f 100644 --- a/src/content/docs/backend/API/tasks.md +++ b/src/content/docs/backend/API/tasks.md @@ -1,16 +1,14 @@ --- -title: Doubtfire API +title: Doubtfire API --- - List of Doubtfire - # API: Tasks + tasks : Operations about tasks -This markdown document provides detailed documentation for the "task" API endpoints including their URLs, methods, parameters, responses, and example requests using curl. +This markdown document provides detailed documentation for the "task" API endpoints including their URLs, methods, parameters, responses, and example requests using curl. This "tasks" API has the following operations. - - **GET** /api/tasks/{task_id}/similarities/{id}/viewer_url - **GET** /api/tasks/{task_id}/similarities/{id}/contents/{idx} - **PUT** /api/tasks/{task_id}/similarities/{id} @@ -19,4 +17,267 @@ This "tasks" API has the following operations. - **POST** /api/tasks/{id}/pin - **GET** /api/tasks -## Detail of Operations related to tasks. \ No newline at end of file +## Detail of Operations related to tasks. + +### GET: Retrieve Viewer URL for Similarity + +GET /api/tasks/{task_id}/similarities/{id}/viewer_url + +- URL: `/api/tasks/{task_id}/similarities/{id}/viewer_url` +- Method: `GET` +- Parameters: + + | Parameter | Description | Parameter Type | Data Type | Mandatory | + | ---------- | -------------------- | -------------- | --------- | --------- | + | task_id | Task ID | path | integer | Yes | + | id | Similarity ID | path | integer | Yes | + | Username | User username | header | string | Yes | + | Auth_Token | Authentication token | header | string | Yes | + +- Response: + `200 OK` + +- Example Request: + + ```bash + curl -X GET --header 'Accept: application/json' --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' + 'http://localhost:3000/api/tasks/1/similarities/1/viewer_url' + ``` + +- Response Body: + ```json + { + "viewer_url": "http://example.com/viewer/123" + } + ``` + +--- + +### GET: Retrieve Similarity Contents + +GET /api/tasks/{task_id}/similarities/{id}/contents/{idx} + +- URL: `/api/tasks/{task_id}/similarities/{id}/contents/{idx}` +- Method: `GET` +- Parameters: + + | Parameter | Description | Parameter Type | Data Type | Mandatory | + | ------------- | -------------------------------------- | -------------- | --------- | --------- | + | task_id | Task ID | path | integer | Yes | + | id | Similarity ID | path | integer | Yes | + | idx | Index of part to download | path | integer | Yes | + | as_attachment | Download file as attachment (optional) | query | boolean | No | + | Username | User username | header | string | Yes | + | Auth_Token | Authentication token | header | string | Yes | + +- Response: + `200 OK` + +- Example Request: + + ```bash + curl -X GET --header 'Accept: application/json' --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' + 'http://localhost:3000/api/tasks/1/similarities/1/contents/0?as_attachment=true' + ``` + +- Response Body: + This endpoint returns the similarity contents as a file. The response does not have a JSON body. + +--- + +### PUT: Update Task Similarity + +PUT /api/tasks/{task_id}/similarities/{id} + +- URL: `/api/tasks/{task_id}/similarities/{id}` +- Method: `PUT` +- Parameters: + + | Parameter | Description | Parameter Type | Data Type | Mandatory | + | ---------- | ------------------------------------- | -------------- | --------- | --------- | + | task_id | Task ID | path | integer | Yes | + | id | Similarity ID | path | integer | Yes | + | flagged | Whether or not to flag the similarity | body | boolean | Yes | + | Username | User username | header | string | Yes | + | Auth_Token | Authentication token | header | string | Yes | + +- Response: + `200 OK` + +- Example Request: + + ```bash + curl -X PUT --header 'Content-Type: application/json' --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' + -d '{"flagged": true}' 'http://localhost:3000/api/tasks/1/similarities/1' + ``` + +- Response Body: + ```json + { + "id": 1, + "task_id": 1, + "flagged": true, + "similarity_details": { + "type": "MOSS", + "pct": 85 + } + } + ``` + +--- + +### GET: Get Task Similarities + +GET /api/tasks/{task_id}/similarities + +- URL: `/api/tasks/{task_id}/similarities` +- Method: `GET` +- Parameters: + + | Parameter | Description | Parameter Type | Data Type | Mandatory | + | ---------- | -------------------- | -------------- | --------- | --------- | + | task_id | Task ID | path | integer | Yes | + | Username | User username | header | string | Yes | + | Auth_Token | Authentication token | header | string | Yes | + +- Response: + `200 OK` + +- Example Request: + + ```bash + curl -X GET --header 'Accept: application/json' --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' + 'http://localhost:3000/api/tasks/1/similarities' + ``` + +- Response Body: + ```json + [ + { + "id": 1, + "task_id": 1, + "similarity_details": { + "type": "MOSS", + "pct": 85 + } + }, + { + "id": 2, + "task_id": 1, + "similarity_details": { + "type": "Turnitin", + "pct": 90 + } + } + ] + ``` + +--- + +### DELETE: Unpin a Task + +DELETE /api/tasks/{id}/pin + +- URL: `/api/tasks/{id}/pin` +- Method: `DELETE` +- Parameters: + + | Parameter | Description | Parameter Type | Data Type | Mandatory | + | ---------- | -------------------- | -------------- | --------- | --------- | + | id | Task ID | path | integer | Yes | + | Username | User username | header | string | Yes | + | Auth_Token | Authentication token | header | string | Yes | + +- Response: + `204` + +- Example Request: + + ```bash + curl -X DELETE --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' + 'http://localhost:3000/api/tasks/1/pin' + + ``` + +- Response Body: + `Task unpinned` + ``` + + ``` + +--- + +### POST: Pin a Task + +POST /api/tasks/{id}/pin + +- URL: `/api/tasks/{id}/pin` +- Method: `POST` +- Parameters: + + | Parameter | Description | Parameter Type | Data Type | Mandatory | + | ---------- | -------------------- | -------------- | --------- | --------- | + | id | Task ID | path | integer | Yes | + | Username | User username | header | string | Yes | + | Auth_Token | Authentication token | header | string | Yes | + +- Response: + `201` + +- Example Request: + ```bash + curl -X POST --header 'Content-Type: application/json' --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' + 'http://localhost:3000/api/tasks/1/pin' + ``` +- Response Body: + ```json + { + "message": "Task successfully pinned" + } + ``` + +--- + +### GET: Retrieve User's Tasks + +GET /api/tasks + +- URL: `/api/tasks` +- Method: `GET` +- Parameters: + + | Parameter | Description | Parameter Type | Data Type | Mandatory | + | ---------- | ------------------------------------- | -------------- | --------- | --------- | + | unit_id | Unit ID to fetch the task details for | query | integer | Yes | + | Username | User username | header | string | Yes | + | Auth_Token | Authentication token | header | string | Yes | + +- Response: + `200 OK` + +- Example Request: + + ```bash + curl -X GET --header 'Accept: application/json' --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' + 'http://localhost:3000/api/tasks?unit_id=1' + ``` + +- Response Body: + ```json + [ + { + "id": 1, + "task_definition_id": 1, + "status": "completed", + "tutorial_id": 1, + "tutorial_stream_id": 1 + }, + { + "id": 2, + "task_definition_id": 2, + "status": "in_progress", + "tutorial_id": 2, + "tutorial_stream_id": 2 + } + ] + ``` diff --git a/src/content/docs/backend/API/tii_actions.md b/src/content/docs/backend/API/tii_actions.md index 1c0c6f7..1f15cee 100644 --- a/src/content/docs/backend/API/tii_actions.md +++ b/src/content/docs/backend/API/tii_actions.md @@ -1,15 +1,97 @@ --- -title: Doubtfire API +title: Doubtfire API --- -# List of Doubtfire - # API: tii_actions + tii_actions : Operations about tii_actions This markdown document provides detailed documentation for the "tii_actions" API endpoints, including their URLs, methods, parameters (if any), responses, and example requests using curl. This "tii_actipns" API has the following operations. + - **PUT** /api/tii_actions/{id} - **GET** /api/tii_actions -## Detail of Operations related to tii_actions. \ No newline at end of file +## Detail of Operations related to tii_actions. + +### GET: Retrieve Outstanding Turnitin Actions + +GET /api/tii_actions + +- URL: `/api/tii_actions` +- Method: `GET` +- Parameters: + + | Parameter | Description | Parameter Type | Data Type | Mandatory | Default | + | ------------- | --------------------------------------- | -------------- | --------- | --------- | ------- | + | unit_id | The ID of the unit to filter by | query | integer | No | nil | + | limit | The maximum number of actions to return | query | integer | No | 50 | + | offset | The offset to start from | query | integer | No | 0 | + | show_complete | Include complete actions? | query | boolean | No | false | + | Username | User username | header | string | Yes | | + | Auth_Token | Authentication token | header | string | Yes | | + +- Response: + `200 OK` + +- Example Request: + + ```bash + curl -X GET --header 'Accept: application/json' --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' + 'http://localhost:3000/api/tii_actions?unit_id=1&limit=10&offset=0&show_complete=false' + ``` + +- Response Body: + ```json + [ + { + "id": 1, + "unit_id": 1, + "action": "Turnitin action details", + "complete": false, + "updated_at": "2023-07-14T10:00:00Z" + }, + { + "id": 2, + "unit_id": 1, + "action": "Another Turnitin action details", + "complete": false, + "updated_at": "2023-07-14T09:00:00Z" + } + ] + ``` + +--- + +### PUT: Trigger an Action on a Turnitin Group Attachment + +PUT /api/tii_actions/{id} + +- URL: `/api/tii_actions/{id}` +- Method: `PUT` +- Parameters: + + | Parameter | Description | Parameter Type | Data Type | Mandatory | Default | + | ---------- | ------------------------------- | -------------- | --------- | --------- | ------- | + | id | The ID of the Turnitin action | path | integer | Yes | | + | action | The action to perform: retry | body | string | Yes | | + | unit_id | The ID of the unit to filter by | body | integer | No | nil | + | Username | User username | header | string | Yes | | + | Auth_Token | Authentication token | header | string | Yes | | + +- Response: + `200 OK` + +- Example Request: + + ```bash + curl -X PUT --header 'Content-Type: application/json' --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' + -d '{"action": "retry", "unit_id": 1}' 'http://localhost:3000/api/tii_actions/1' + ``` + +- Response Body: + ```json + { + "message": "Retry action triggered successfully" + } + ``` From 8882b8a2db59cab0e2547df258598eb800277c5b Mon Sep 17 00:00:00 2001 From: minusunil Date: Sat, 10 Aug 2024 09:12:34 +1000 Subject: [PATCH 2/5] Operations about API units --- astro.config.mjs | 4 + .../docs/backend/API/api-task_definitions.md | 118 ++++++++++++++++++ 2 files changed, 122 insertions(+) create mode 100644 src/content/docs/backend/API/api-task_definitions.md diff --git a/astro.config.mjs b/astro.config.mjs index c8086de..90c0019 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -155,6 +155,10 @@ export default defineConfig({ label: 'Error codes', link: '/backend/api/error_codes', }, + { + label: 'Units Task Definition', + link: '/backend/api/api-task_definitions', + }, ], }, { diff --git a/src/content/docs/backend/API/api-task_definitions.md b/src/content/docs/backend/API/api-task_definitions.md new file mode 100644 index 0000000..7dfcef8 --- /dev/null +++ b/src/content/docs/backend/API/api-task_definitions.md @@ -0,0 +1,118 @@ +--- +title: Doubtfire API +--- + +# API: units + +units : Operations about units +This markdown document provides detailed documentation for the "units" API endpoints, including their URLs, methods, parameters (if any), responses, and example requests using curl. + +This "units" API has the following operations. + +- **DELETE**: /api/units/{unit_id}/task_definitions/{task_def_id}/tii_group_attachments/{id} +- **PUT**: /api/units/{unit_id}/task_definitions/{task_def_id}/tii_group_attachments/{id} +- **GET**: /api/units/{unit_id}/task_definitions/{task_def_id}/tii_group_attachments + +## Detail of Operations related to units. + +### GET: Get the group attachments for a given task definition. + +GET /units/{unit_id}/task_definitions/{task_def_id}/tii_group_attachments + +- URL: `/units/{unit_id}/task_definitions/{task_def_id}/tii_group_attachments` +- Method: `GET` +- Parameters: + | Parameter | Description |Parameter Type| Data Type|Mandatory| + |---------------------|-----------------|--------------|----------|---| + |unit_id | Unit ID | path | integer |Yes| + |task_def_id | Task Definition ID | path | integer |Yes| + |Username | User username | header | string |Yes| + |Auth_Token | Authentication token | header | string |Yes| + +- Response: + `200 OK` + +- Example Request: + + ```bash + curl -X GET --header 'Accept: application/json' --header 'Username: aadmin' --header 'Auth_Token: yzRDggcmzbVnYEbszVV1' 'http://localhost:3000/units/1/task_definitions/1/tii_group_attachments' + ``` + +- Response body: + ```json + [ + { + "id": 1, + "name": "Attachment 1", + "status": "uploaded" + }, + { + "id": 2, + "name": "Attachment 2", + "status": "pending" + } + ] + ``` + +### PUT: Trigger an action on the given group attachment. + +PUT /units/{unit_id}/task_definitions/{task_def_id}/tii_group_attachments/{id} + +- URL: `/units/{unit_id}/task_definitions/{task_def_id}/tii_group_attachments/{id}` +- Method: `PUT` +- Parameters: + | Parameter | Description |Parameter Type| Data Type|Mandatory| + |---------------------|-----------------|--------------|----------|---| + |unit_id | Unit ID | path | integer |Yes| + |task_def_id | Task Definition ID | path | integer |Yes| + |id | Group Attachment ID | path | integer |Yes| + |action | The action to perform (e.g., upload) | query | string |Yes| + |Username | User username | header | string |Yes| + |Auth_Token | Authentication token | header | string |Yes| + +- Response: + `200 OK` + +- Example Request: + + ```bash + curl -X PUT --header 'Accept: application/json' --header 'Username: aadmin' --header 'Auth_Token: yzRDggcmzbVnYEbszVV1' -d 'action=upload' 'http://localhost:3000/units/1/task_definitions/1/tii_group_attachments/1' + ``` + +- Response body: + ```json + { + "id": 1, + "name": "Attachment 1", + "status": "has_id" + } + ``` + +### DELETE: Delete a group attachment. + +DELETE /units/{unit_id}/task_definitions/{task_def_id}/tii_group_attachments/{id} + +- URL: `/units/{unit_id}/task_definitions/{task_def_id}/tii_group_attachments/{id}` +- Method: `DELETE` +- Parameters: + | Parameter | Description |Parameter Type| Data Type|Mandatory| + |---------------------|-----------------|--------------|----------|---| + |unit_id | Unit ID | path | integer |Yes| + |task_def_id | Task Definition ID | path | integer |Yes| + |id | Group Attachment ID | path | integer |Yes| + |Username | User username | header | string |Yes| + |Auth_Token | Authentication token | header | string |Yes| + +- Response: + `204` + +- Example Request: + + ```bash + curl -X DELETE --header 'Accept: application/json' --header 'Username: aadmin' --header 'Auth_Token: yzRDggcmzbVnYEbszVV1' 'http://localhost:3000/units/1/task_definitions/1/tii_group_attachments/1' + ``` + +- Response body: + ``` + true + ``` From 01f6ca3080ba5e7cd032596d427cad42faf2ee78 Mon Sep 17 00:00:00 2001 From: minusunil Date: Sun, 11 Aug 2024 18:49:05 +1000 Subject: [PATCH 3/5] updated the admin page --- src/content/docs/backend/API/admin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/backend/API/admin.md b/src/content/docs/backend/API/admin.md index 84b929e..39d2b8b 100644 --- a/src/content/docs/backend/API/admin.md +++ b/src/content/docs/backend/API/admin.md @@ -66,7 +66,7 @@ GET /api/admin/overseer_images - Example Request: ```bash - curl -X PUT --header 'Accept: application/json' --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' 'http://localhost:3000/api/admin/overseer_images' + curl -X GET --header 'Accept: application/json' --header 'Username: admin' --header 'Auth_Token: rrK8BdRfxof9RrJGuk5n' 'http://localhost:3000/api/admin/overseer_images' ``` - Response Body: ```json From 62569a5ff0a661f10db7dfc4109dce16d8a605ec Mon Sep 17 00:00:00 2001 From: minusunil Date: Thu, 22 Aug 2024 19:59:14 +1000 Subject: [PATCH 4/5] formatted content --- .../docs/backend/API/api-task_definitions.md | 48 +++++++++---------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/src/content/docs/backend/API/api-task_definitions.md b/src/content/docs/backend/API/api-task_definitions.md index 7dfcef8..0d24d8f 100644 --- a/src/content/docs/backend/API/api-task_definitions.md +++ b/src/content/docs/backend/API/api-task_definitions.md @@ -2,10 +2,10 @@ title: Doubtfire API --- -# API: units +# API: units - Task Definitions -units : Operations about units -This markdown document provides detailed documentation for the "units" API endpoints, including their URLs, methods, parameters (if any), responses, and example requests using curl. +units : Operations about Units +This markdown document provides detailed documentation for the "Task definition" API endpoints, including their URLs, methods, parameters (if any), responses, and example requests using curl. This "units" API has the following operations. @@ -22,12 +22,12 @@ GET /units/{unit_id}/task_definitions/{task_def_id}/tii_group_attachments - URL: `/units/{unit_id}/task_definitions/{task_def_id}/tii_group_attachments` - Method: `GET` - Parameters: - | Parameter | Description |Parameter Type| Data Type|Mandatory| - |---------------------|-----------------|--------------|----------|---| - |unit_id | Unit ID | path | integer |Yes| - |task_def_id | Task Definition ID | path | integer |Yes| - |Username | User username | header | string |Yes| - |Auth_Token | Authentication token | header | string |Yes| + | Parameter | Description |Parameter Type| Data Type|Mandatory| + |---------------------|----------------------|--------------|----------|---------| + |unit_id | Unit ID | path | integer |Yes | + |task_def_id | Task Definition ID | path | integer |Yes | + |Username | User username | header | string |Yes | + |Auth_Token | Authentication token | header | string |Yes | - Response: `200 OK` @@ -61,14 +61,14 @@ PUT /units/{unit_id}/task_definitions/{task_def_id}/tii_group_attachments/{id} - URL: `/units/{unit_id}/task_definitions/{task_def_id}/tii_group_attachments/{id}` - Method: `PUT` - Parameters: - | Parameter | Description |Parameter Type| Data Type|Mandatory| - |---------------------|-----------------|--------------|----------|---| - |unit_id | Unit ID | path | integer |Yes| - |task_def_id | Task Definition ID | path | integer |Yes| - |id | Group Attachment ID | path | integer |Yes| - |action | The action to perform (e.g., upload) | query | string |Yes| - |Username | User username | header | string |Yes| - |Auth_Token | Authentication token | header | string |Yes| + | Parameter | Description |Parameter Type| Data Type|Mandatory| + |------------|--------------------------------------|--------------|----------|---------| + |unit_id | Unit ID | path | integer |Yes | + |task_def_id | Task Definition ID | path | integer |Yes | + |id | Group Attachment ID | path | integer |Yes | + |action | The action to perform (e.g., upload) | query | string |Yes | + |Username | User username | header | string |Yes | + |Auth_Token | Authentication token | header | string |Yes | - Response: `200 OK` @@ -95,13 +95,13 @@ DELETE /units/{unit_id}/task_definitions/{task_def_id}/tii_group_attachments/{id - URL: `/units/{unit_id}/task_definitions/{task_def_id}/tii_group_attachments/{id}` - Method: `DELETE` - Parameters: - | Parameter | Description |Parameter Type| Data Type|Mandatory| - |---------------------|-----------------|--------------|----------|---| - |unit_id | Unit ID | path | integer |Yes| - |task_def_id | Task Definition ID | path | integer |Yes| - |id | Group Attachment ID | path | integer |Yes| - |Username | User username | header | string |Yes| - |Auth_Token | Authentication token | header | string |Yes| + | Parameter | Description |Parameter Type| Data Type|Mandatory| + |------------|----------------------|--------------|----------|---------| + |unit_id | Unit ID | path | integer |Yes | + |task_def_id | Task Definition ID | path | integer |Yes | + |id | Group Attachment ID | path | integer |Yes | + |Username | User username | header | string |Yes | + |Auth_Token | Authentication token | header | string |Yes | - Response: `204` From 7ab956d9e034bea9668131a5d7692743a5388421 Mon Sep 17 00:00:00 2001 From: minusunil Date: Tue, 27 Aug 2024 17:40:02 +1000 Subject: [PATCH 5/5] new units api's task definition added --- .../docs/backend/API/api-task_definitions.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) diff --git a/src/content/docs/backend/API/api-task_definitions.md b/src/content/docs/backend/API/api-task_definitions.md index 0d24d8f..b8cc240 100644 --- a/src/content/docs/backend/API/api-task_definitions.md +++ b/src/content/docs/backend/API/api-task_definitions.md @@ -12,6 +12,11 @@ This "units" API has the following operations. - **DELETE**: /api/units/{unit_id}/task_definitions/{task_def_id}/tii_group_attachments/{id} - **PUT**: /api/units/{unit_id}/task_definitions/{task_def_id}/tii_group_attachments/{id} - **GET**: /api/units/{unit_id}/task_definitions/{task_def_id}/tii_group_attachments +- **DELETE**: /api/units/{unit_id}/task_definitions/{task_def_id}/task_resources +- **GET**: /api/units/{unit_id}/task_definitions/{task_def_id}/task_resources +- **POST**: /api/units/{unit_id}/task_definitions/{task_def_id}/task_resources +- **POST**: /api/units/{unit_id}/task_definitions/{task_def_id}/task_sheet +- **POST**: /api/units/{unit_id}/task_definitions/{task_def_id}/test_overseer_assessment ## Detail of Operations related to units. @@ -116,3 +121,149 @@ DELETE /units/{unit_id}/task_definitions/{task_def_id}/tii_group_attachments/{id ``` true ``` + +### DELETE: Remove the task resources for a given task + +DELETE /units/{unit_id}/task_definitions/{task_def_id}/task_resources + +- URL: `/units/{unit_id}/task_definitions/{task_def_id}/task_resources` +- Method: `DELETE` +- Parameters: + | Parameter | Description |Parameter Type| Data Type|Mandatory| + |------------|----------------------|--------------|----------|---------| + |unit_id | Unit ID | path | integer |Yes | + |task_def_id | Task Definition ID | path | integer |Yes | + |Username | User username | header | string |Yes | + |Auth_Token | Authentication token | header | string |Yes | + +- Response: + `204` + +- Example Request: + + ```bash + curl -X DELETE --header 'Accept: application/json' --header 'Username: aadmin' --header 'Auth_Token: yzRDggcmzbVnYEbszVV1' 'http://localhost:3000/units/1/task_definitions/1/task_resources' + ``` + +- Response body: + ``` + true + ``` + +### GET: Download the task resources + +GET /units/{unit_id}/task_definitions/{task_def_id}/task_resources + +- URL: `/units/{unit_id}/task_definitions/{task_def_id}/task_resources` +- Method: `GET` +- Parameters: + | Parameter | Description |Parameter Type| Data Type|Mandatory| + |------------|----------------------|--------------|----------|---------| + |unit_id | Unit ID | path | integer |Yes | + |task_def_id | Task Definition ID | path | integer |Yes | + |Username | User username | header | string |Yes | + |Auth_Token | Authentication token | header | string |Yes | + +- Response: + `200 OK` + +- Example Request: + + ```bash + curl -X GET --header 'Accept: application/json' --header 'Username: aadmin' --header 'Auth_Token: yzRDggcmzbVnYEbszVV1' 'http://localhost:3000/units/1/task_definitions/1/task_resources' + ``` + +- Response body: + ``` + + ``` + +### POST: Upload the task resources for a given task + +POST /units/{unit_id}/task_definitions/{task_def_id}/task_resources + +- URL: `/units/{unit_id}/task_definitions/{task_def_id}/task_resources` +- Method: `POST` +- Parameters: + | Parameter | Description |Parameter Type| Data Type|Mandatory| + |------------|----------------------|--------------|----------|---------| + |unit_id | Unit ID | path | integer |Yes | + |task_def_id | Task Definition ID | path | integer |Yes | + |Username | User username | header | string |Yes | + |Auth_Token | Authentication token | header | string |Yes | + |file | Task resources zip | form-data | file |Yes | + +- Response: + `200 OK` + +- Example Request: + + ```bash + curl -X POST --header 'Accept: application/json' --header 'Username: aadmin' --header 'Auth_Token: yzRDggcmzbVnYEbszVV1' -F "file=@/path/to/resources.zip" 'http://localhost:3000/units/1/task_definitions/1/task_resources' + ``` + +- Response body: + ``` + true + ``` + +### POST: Upload the task sheet for a given task + +POST /units/{unit_id}/task_definitions/{task_def_id}/task_sheet + +- URL: `/units/{unit_id}/task_definitions/{task_def_id}/task_sheet` +- Method: `POST` +- Parameters: + | Parameter | Description |Parameter Type| Data Type|Mandatory| + |------------|----------------------|--------------|----------|---------| + |unit_id | Unit ID | path | integer |Yes | + |task_def_id | Task Definition ID | path | integer |Yes | + |Username | User username | header | string |Yes | + |Auth_Token | Authentication token | header | string |Yes | + |file | Task resources zip | form-data | file |Yes | + +- Response: + `200 OK` + +- Example Request: + + ```bash + curl -X POST --header 'Accept: application/json' --header 'Username: aadmin' --header 'Auth_Token: yzRDggcmzbVnYEbszVV1' -F "file=@/path/to/task_sheet.pdf" 'http://localhost:3000/units/1/task_definitions/1/task_sheet' + ``` + +- Response body: + ``` + true + ``` + +### POST: Test overseer assessment for a given task + +POST /units/{unit_id}/task_definitions/{task_def_id}/test_overseer_assessment + +- URL: `/units/{unit_id}/task_definitions/{task_def_id}/test_overseer_assessment` +- Method: `POST` +- Parameters: + | Parameter | Description |Parameter Type| Data Type|Mandatory| + |------------|----------------------|--------------|----------|---------| + |unit_id | Unit ID | path | integer |Yes | + |task_def_id | Task Definition ID | path | integer |Yes | + |Username | User username | header | string |Yes | + |Auth_Token | Authentication token | header | string |Yes | + |file 0 | File 0 (optional) | form-data | file |No | + |file 1 | File 1 (optional) | form-data | file |No | + +- Response: + `200 OK` + +- Example Request: + + ```bash + curl -X POST --header 'Accept: application/json' --header 'Username: aadmin' --header 'Auth_Token: yzRDggcmzbVnYEbszVV1' -F "file0=@/path/to/file0" -F "file1=@/path/to/file1" 'http://localhost:3000/units/1/task_definitions/1/test_overseer_assessment' + ``` + +- Response body: + ```json + { + "status": "Overseer assessment performed successfully" + } + ```