Skip to content

Commit 2b3f151

Browse files
VaibhavSingh8VaibhavSingh8
authored
API contract for Todo app (#231)
* docs: todo-backend api contract * docs: fixed few issues * docs: fixed response structure * Update README.md * docs: fixed response structure and task object fields
1 parent b1d1c2f commit 2b3f151

File tree

1 file changed

+312
-0
lines changed

1 file changed

+312
-0
lines changed

‎todo-backend/README.md‎

Lines changed: 312 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,312 @@
1+
# Todo Backend
2+
3+
#### Task Object:
4+
5+
```
6+
{
7+
id: <ObjectId>
8+
taskId: <string>
9+
title: <string>
10+
description: <string> | null
11+
priority: LOW | MEDIUM | HIGH
12+
status: TODO | IN_PROGRESS | DONE
13+
assignee: {
14+
id: <string>
15+
name: <string>
16+
} | null
17+
labels: [
18+
{
19+
name: <string>
20+
color: <string>
21+
createdAt: <datetime> | null
22+
updatedAt: <datetime> | null
23+
createdBy: {
24+
id: <string>
25+
name: <string>
26+
} | null
27+
updatedBy: {
28+
id: <string>
29+
name: <string>
30+
} | null
31+
}
32+
]
33+
isAcknowledged: <boolean>
34+
isDeleted: <boolean>
35+
deferredDetails: {
36+
deferredAt: <datetime> | null
37+
deferredTill: <datetime> | null
38+
deferredBy: <string> | null
39+
}
40+
dueDate: <datetime>
41+
startDate: <datetime> | null
42+
createdAt: <datetime>
43+
updatedAt: <datetime> | null
44+
createdBy: <string>
45+
updatedBy: <string> | null
46+
}
47+
```
48+
49+
#### DeferredDetails Object:
50+
51+
```
52+
{
53+
deferredDate: <datetime> | null
54+
deferredTill: <datetime> | null
55+
deferredBy: <string> | null
56+
}
57+
```
58+
59+
## **Requests**
60+
61+
| Route | Description |
62+
| :---------------------------: | :------------------------------: |
63+
| [GET /v1/tasks](#get-tasks) | Return all tasks with pagination |
64+
| [POST /v1/tasks](#post-tasks) | Creates new task |
65+
| [GET /v1/health](#get-health) | Health check endpoint |
66+
67+
## **GET /v1/tasks**
68+
69+
Return all tasks with pagination support
70+
71+
- **Params**
72+
None
73+
- **Query**
74+
75+
- Optional: `page=[integer]` (Page number for pagination, default: 1)
76+
- Optional: `limit=[integer]` (Number of items per page, default: from Settings)
77+
78+
- **Success Response:**
79+
80+
- **Code:** 200
81+
- **Content:**
82+
```json
83+
{
84+
"statusCode": 200,
85+
"sucessMessage": "Tasks retrieved successfully",
86+
"data": [
87+
{
88+
"id": "<string>",
89+
"taskId": "<string>",
90+
"title": "<string>",
91+
"description": "<string> | null",
92+
"priority": "LOW | MEDIUM | HIGH",
93+
"status": "TODO | IN_PROGRESS | DONE",
94+
"assignee": {
95+
"id": "<string>",
96+
"name": "<string>"
97+
} | null,
98+
"isAcknowledged": "<boolean>",
99+
"labels": [
100+
{
101+
"name": "<string>",
102+
"color": "<string>",
103+
"createdAt": "<datetime> | null",
104+
"updatedAt": "<datetime> | null",
105+
"createdBy": {
106+
"id": "<string>",
107+
"name": "<string>"
108+
} | null,
109+
"updatedBy": {
110+
"id": "<string>",
111+
"name": "<string>"
112+
} | null
113+
}
114+
],
115+
"startDate": "<datetime> | null",
116+
"dueDate": "<datetime> | null",
117+
"createdAt": "<datetime>",
118+
"updatedAt": "<datetime> | null",
119+
"createdBy": {
120+
"id": "<string>",
121+
"name": "<string>"
122+
},
123+
"updatedBy": {
124+
"id": "<string>",
125+
"name": "<string>"
126+
} | null
127+
}
128+
],
129+
"links": {
130+
"next": "<string> | null",
131+
"prev": "<string> | null"
132+
},
133+
"count":"number"
134+
}
135+
```
136+
137+
- **Error Response:**
138+
139+
- **Code:** 400
140+
- **Content:**
141+
142+
```json
143+
{
144+
"status": "validation_failed",
145+
"statusCode": 400,
146+
"errorMessage": "Validation Error",
147+
"errors": [
148+
{
149+
"field": "<string>",
150+
"message": "<string>"
151+
}
152+
<!-- Example {
153+
"field": "page",
154+
"message": "page must be greater than or equal to 1"
155+
} -->
156+
]
157+
}
158+
```
159+
160+
- **Code:** 500
161+
- **Content:**
162+
163+
```json
164+
{
165+
"statusCode": 500,
166+
"errorMessage": "An unexpected error occurred",
167+
"errors": [
168+
{
169+
"detail": "Internal server error"
170+
}
171+
]
172+
}
173+
```
174+
175+
## **POST /v1/tasks**
176+
177+
Creates a new task
178+
179+
- **Params**
180+
None
181+
- **Body**
182+
183+
```json
184+
{
185+
"title": "<string>",
186+
"description": "<string> | null",
187+
"priority": "LOW | MEDIUM | HIGH",
188+
"status": "TODO | IN_PROGRESS | DONE",
189+
"assignee": "<string> | null",
190+
"labels": ["<ObjectId>"],
191+
"dueDate": "<datetime>"
192+
}
193+
```
194+
195+
- **Success Response:**
196+
197+
- **Code:** 201
198+
- **Content:**
199+
```json
200+
{
201+
"statusCode": 201,
202+
"sucessMessage": "Task created successfully",
203+
"data": {
204+
"id": "<string>",
205+
"taskId": "<string>", // "TASK-1001"
206+
"title": "<string>",
207+
"description": "<string> | null",
208+
"priority": "LOW | MEDIUM | HIGH",
209+
"status": "TODO | IN_PROGRESS | DONE",
210+
"assignee": {
211+
"id": "<string>",
212+
"name": "<string>"
213+
} | null,
214+
"isAcknowledged": "<boolean>",
215+
"labels": [
216+
{
217+
"name": "<string>",
218+
"color": "<string>",
219+
"createdAt": "<datetime>",
220+
"updatedAt": null,
221+
"createdBy": {
222+
"id": "<string>",
223+
"name": "<string>"
224+
},
225+
"updatedBy": null
226+
}
227+
],
228+
"startDate": null,
229+
"dueDate": "<datetime> | null",
230+
"createdAt": "<datetime>",
231+
"updatedAt": null,
232+
"createdBy": {
233+
"id": "<string>",
234+
"name": "<string>"
235+
},
236+
"updatedBy": null
237+
}
238+
}
239+
```
240+
241+
- **Error Response:**
242+
- **Code:** 400
243+
- **Content:**
244+
```json
245+
{
246+
"status": "validation_failed"
247+
"statusCode": 400,
248+
"errorMessage": "Validation Error",
249+
"errors": [
250+
{
251+
"field": "<string>",
252+
"message": "<string>"
253+
},
254+
<!-- Example {
255+
"field": "title",
256+
"message": "This field is required"
257+
} -->
258+
]
259+
}
260+
```
261+
- **Code:** 500
262+
- **Content:**
263+
```json
264+
{
265+
"status": "internal_server_error"
266+
"statusCode": 500,
267+
"errorMessage": "An unexpected error occurred",
268+
"errors": [
269+
{
270+
"detail": "Internal server error"
271+
}
272+
]
273+
}
274+
```
275+
276+
## **GET /v1/health**
277+
278+
Health check endpoint
279+
280+
- **Params**
281+
None
282+
- **Query**
283+
None
284+
285+
- **Success Response:**
286+
287+
- **Code:** 200
288+
- **Content:**
289+
```json
290+
{
291+
"status": "healthy"
292+
}
293+
```
294+
295+
- **Error Response:**
296+
- **Code:** 500
297+
- **Content:**
298+
```json
299+
{
300+
"status": "unhealthy"
301+
}
302+
```
303+
304+
## **Error Codes**
305+
306+
| Status Code | Description |
307+
| :---------: | :----------------------------: |
308+
| 200 | Success |
309+
| 201 | Created |
310+
| 400 | Bad Request (Validation Error) |
311+
| 404 | Not Found |
312+
| 500 | Internal Server Error |

0 commit comments

Comments
 (0)