From 01a1f6ba9a37ed405f55ee3b4eb5327edaf40a7c Mon Sep 17 00:00:00 2001 From: Vaibhav Singh Date: Thu, 3 Apr 2025 22:57:36 +0530 Subject: [PATCH 1/5] docs: todo-backend api contract --- todo-backend/README.md | 179 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 todo-backend/README.md diff --git a/todo-backend/README.md b/todo-backend/README.md new file mode 100644 index 0000000..29c5d56 --- /dev/null +++ b/todo-backend/README.md @@ -0,0 +1,179 @@ +# Todo Backend + +#### Task Object: + +``` +{ + id: + displayId: + title: + description: | null + priority: LOW | MEDIUM | HIGH + status: TODO | IN_PROGRESS | DONE + assignee: | null + labels: [] + isAcknowledged: + isDeleted: + deferredDetails: { + deferredAt: | null + deferredTill: | null + deferredBy: | null + } + dueAt: + startedAt: | null + createdAt: + updatedAt: | null + createdBy: + updatedBy: | null +} +``` + +#### DeferredDetails Object: + +``` +{ + deferredAt: | null + deferredTill: | null + deferredBy: | null +} +``` + +## **Requests** + +| Route | Description | +| :---------------------------: | :------------------------------: | +| [GET /v1/tasks](#get-tasks) | Return all tasks with pagination | +| [POST /v1/tasks](#post-tasks) | Creates new task | +| [GET /v1/health](#get-health) | Health check endpoint | + +## **GET /v1/tasks** + +Return all tasks with pagination support + +- **Params** + None +- **Query** + + - Required: `page=[integer]` (Page number for pagination) + - Required: `limit=[integer]` (Number of items per page) + +- **Success Response:** + + - **Code:** 200 + - **Content:** + ```json + { + "tasks": [ + { + // Task object + } + ], + "total": "", + "page": "", + "limit": "" + } + ``` + +- **Error Response:** + - **Code:** 400 + - **Content:** + ```json + { + "statusCode": 400, + "message": "Validation Error", + "errors": [ + { + "source": { + "parameter": "" + }, + "detail": "" + } + ] + } + ``` + +## **POST /v1/tasks** + +Creates a new task + +- **Params** + None +- **Body** + + ```json + { + "title": "", + "description": " | null", + "priority": "LOW | MEDIUM | HIGH", + "status": "TODO | IN_PROGRESS | DONE", + "assignee": " | null", + "labels": [""], + "dueAt": "" + } + ``` + +- **Success Response:** + + - **Code:** 201 + - **Content:** + ```json + { + // Created Task object + } + ``` + +- **Error Response:** + - **Code:** 400 + - **Content:** + ```json + { + "statusCode": 400, + "message": "Validation Error", + "errors": [ + { + "source": { + "parameter": "" + }, + "detail": "" + } + ] + } + ``` + +## **GET /v1/health** + +Health check endpoint + +- **Params** + None +- **Query** + None + +- **Success Response:** + + - **Code:** 200 + - **Content:** + ```json + { + "status": "healthy" + } + ``` + +- **Error Response:** + - **Code:** 500 + - **Content:** + ```json + { + "status": "unhealthy" + } + ``` + +## **Error Codes** + +| Status Code | Description | +| :---------: | :----------------------------: | +| 200 | Success | +| 201 | Created | +| 400 | Bad Request (Validation Error) | +| 404 | Not Found | +| 500 | Internal Server Error | From f54a5a3741b6c80f196d41b5b3802c15a4ad65d0 Mon Sep 17 00:00:00 2001 From: Vaibhav Singh Date: Fri, 4 Apr 2025 01:12:29 +0530 Subject: [PATCH 2/5] docs: fixed few issues --- todo-backend/README.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/todo-backend/README.md b/todo-backend/README.md index 29c5d56..b433a85 100644 --- a/todo-backend/README.md +++ b/todo-backend/README.md @@ -131,10 +131,21 @@ Creates a new task "message": "Validation Error", "errors": [ { - "source": { - "parameter": "" - }, - "detail": "" + "field": "", + "message": "" + } + ] + } + ``` + - **Code:** 500 + - **Content:** + ```json + { + "statusCode": 500, + "message": "An unexpected error occurred", + "errors": [ + { + "detail": "Internal server error" } ] } From ecbcadf0184e13933fdda23fe1ef27ad8eb80e14 Mon Sep 17 00:00:00 2001 From: Vaibhav Singh Date: Fri, 4 Apr 2025 01:27:39 +0530 Subject: [PATCH 3/5] docs: fixed response structure --- todo-backend/README.md | 47 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 43 insertions(+), 4 deletions(-) diff --git a/todo-backend/README.md b/todo-backend/README.md index b433a85..135b85f 100644 --- a/todo-backend/README.md +++ b/todo-backend/README.md @@ -65,12 +65,51 @@ Return all tasks with pagination support { "tasks": [ { - // Task object + "id": "", + "displayId": "", + "title": "", + "description": " | null", + "priority": "LOW | MEDIUM | HIGH", + "status": "TODO | IN_PROGRESS | DONE", + "assignee": { + "id": "", + "name": "" + } | null, + "isAcknowledged": "", + "labels": [ + { + "name": "", + "color": "", + "createdAt": " | null", + "updatedAt": " | null", + "createdBy": { + "id": "", + "name": "" + } | null, + "updatedBy": { + "id": "", + "name": "" + } | null + } + ], + "startedAt": " | null", + "dueAt": " | null", + "createdAt": "", + "updatedAt": " | null", + "createdBy": { + "id": "", + "name": "" + }, + "updatedBy": { + "id": "", + "name": "" + } | null } ], - "total": "", - "page": "", - "limit": "" + "links": { + "next": " | null", + "prev": " | null" + } } ``` From 9470ce0dffaf949cf69b8553220d7274bb38f4b8 Mon Sep 17 00:00:00 2001 From: Vaibhav Singh Date: Fri, 4 Apr 2025 01:57:33 +0530 Subject: [PATCH 4/5] Update README.md --- todo-backend/README.md | 57 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 51 insertions(+), 6 deletions(-) diff --git a/todo-backend/README.md b/todo-backend/README.md index 135b85f..adf6a83 100644 --- a/todo-backend/README.md +++ b/todo-backend/README.md @@ -54,8 +54,8 @@ Return all tasks with pagination support None - **Query** - - Required: `page=[integer]` (Page number for pagination) - - Required: `limit=[integer]` (Number of items per page) + - Optional: `page=[integer]` (Page number for pagination, defaults to 1) + - Optional: `limit=[integer]` (Number of items per page) - **Success Response:** @@ -118,6 +118,7 @@ Return all tasks with pagination support - **Content:** ```json { + "status": "validation_failed", "statusCode": 400, "message": "Validation Error", "errors": [ @@ -157,8 +158,48 @@ Creates a new task - **Content:** ```json { - // Created Task object - } + "task": { + "id": "", + "displayId": "", + "title": "", + "description": " | null", + "priority": "LOW | MEDIUM | HIGH", + "status": "TODO | IN_PROGRESS | DONE", + "assignee": { + "id": "", + "name": "" + } | null, + "isAcknowledged": "", + "labels": [ + { + "name": "", + "color": "", + "createdAt": " | null", + "updatedAt": " | null", + "createdBy": { + "id": "", + "name": "" + } | null, + "updatedBy": { + "id": "", + "name": "" + } | null + } + ], + "startedAt": " | null", + "dueAt": " | null", + "createdAt": "", + "updatedAt": " | null", + "createdBy": { + "id": "", + "name": "" + }, + "updatedBy": { + "id": "", + "name": "" + } | null + } + }, ``` - **Error Response:** @@ -166,12 +207,15 @@ Creates a new task - **Content:** ```json { + "status": "validation_failed" "statusCode": 400, "message": "Validation Error", "errors": [ { - "field": "", - "message": "" + "source": { + "parameter": "" + }, + "detail": "" } ] } @@ -180,6 +224,7 @@ Creates a new task - **Content:** ```json { + "status": "internal_server_error" "statusCode": 500, "message": "An unexpected error occurred", "errors": [ From 1f191f9e9dd777708eac5c38d665b04765f4d976 Mon Sep 17 00:00:00 2001 From: Vaibhav Singh Date: Sun, 6 Apr 2025 20:28:04 +0530 Subject: [PATCH 5/5] docs: fixed response structure and task object fields --- todo-backend/README.md | 124 +++++++++++++++++++++++++++-------------- 1 file changed, 81 insertions(+), 43 deletions(-) diff --git a/todo-backend/README.md b/todo-backend/README.md index adf6a83..493bc5f 100644 --- a/todo-backend/README.md +++ b/todo-backend/README.md @@ -5,13 +5,31 @@ ``` { id: - displayId: + taskId: title: description: | null priority: LOW | MEDIUM | HIGH status: TODO | IN_PROGRESS | DONE - assignee: | null - labels: [] + assignee: { + id: + name: + } | null + labels: [ + { + name: + color: + createdAt: | null + updatedAt: | null + createdBy: { + id: + name: + } | null + updatedBy: { + id: + name: + } | null + } + ] isAcknowledged: isDeleted: deferredDetails: { @@ -19,8 +37,8 @@ deferredTill: | null deferredBy: | null } - dueAt: - startedAt: | null + dueDate: + startDate: | null createdAt: updatedAt: | null createdBy: @@ -32,7 +50,7 @@ ``` { - deferredAt: | null + deferredDate: | null deferredTill: | null deferredBy: | null } @@ -54,8 +72,8 @@ Return all tasks with pagination support None - **Query** - - Optional: `page=[integer]` (Page number for pagination, defaults to 1) - - Optional: `limit=[integer]` (Number of items per page) + - Optional: `page=[integer]` (Page number for pagination, default: 1) + - Optional: `limit=[integer]` (Number of items per page, default: from Settings) - **Success Response:** @@ -63,10 +81,12 @@ Return all tasks with pagination support - **Content:** ```json { - "tasks": [ + "statusCode": 200, + "sucessMessage": "Tasks retrieved successfully", + "data": [ { "id": "", - "displayId": "", + "taskId": "", "title": "", "description": " | null", "priority": "LOW | MEDIUM | HIGH", @@ -92,8 +112,8 @@ Return all tasks with pagination support } | null } ], - "startedAt": " | null", - "dueAt": " | null", + "startDate": " | null", + "dueDate": " | null", "createdAt": "", "updatedAt": " | null", "createdBy": { @@ -109,24 +129,44 @@ Return all tasks with pagination support "links": { "next": " | null", "prev": " | null" - } + }, + "count":"number" } ``` - **Error Response:** + - **Code:** 400 - **Content:** + ```json { "status": "validation_failed", "statusCode": 400, - "message": "Validation Error", + "errorMessage": "Validation Error", "errors": [ { - "source": { - "parameter": "" - }, - "detail": "" + "field": "", + "message": "" + } + + ] + } + ``` + + - **Code:** 500 + - **Content:** + + ```json + { + "statusCode": 500, + "errorMessage": "An unexpected error occurred", + "errors": [ + { + "detail": "Internal server error" } ] } @@ -148,7 +188,7 @@ Creates a new task "status": "TODO | IN_PROGRESS | DONE", "assignee": " | null", "labels": [""], - "dueAt": "" + "dueDate": "" } ``` @@ -158,9 +198,11 @@ Creates a new task - **Content:** ```json { - "task": { + "statusCode": 201, + "sucessMessage": "Task created successfully", + "data": { "id": "", - "displayId": "", + "taskId": "", // "TASK-1001" "title": "", "description": " | null", "priority": "LOW | MEDIUM | HIGH", @@ -174,32 +216,26 @@ Creates a new task { "name": "", "color": "", - "createdAt": " | null", - "updatedAt": " | null", + "createdAt": "", + "updatedAt": null, "createdBy": { "id": "", "name": "" - } | null, - "updatedBy": { - "id": "", - "name": "" - } | null + }, + "updatedBy": null } ], - "startedAt": " | null", - "dueAt": " | null", + "startDate": null, + "dueDate": " | null", "createdAt": "", - "updatedAt": " | null", + "updatedAt": null, "createdBy": { "id": "", "name": "" }, - "updatedBy": { - "id": "", - "name": "" - } | null + "updatedBy": null } - }, + } ``` - **Error Response:** @@ -209,14 +245,16 @@ Creates a new task { "status": "validation_failed" "statusCode": 400, - "message": "Validation Error", + "errorMessage": "Validation Error", "errors": [ { - "source": { - "parameter": "" - }, - "detail": "" - } + "field": "", + "message": "" + }, + ] } ``` @@ -226,7 +264,7 @@ Creates a new task { "status": "internal_server_error" "statusCode": 500, - "message": "An unexpected error occurred", + "errorMessage": "An unexpected error occurred", "errors": [ { "detail": "Internal server error"