File size: 3,211 Bytes
e566277 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 | # Backend API Contract
**Purpose**: Document Phase III backend API endpoints for chatbot integration
**Version**: 1.0.0 (Phase III - READ-ONLY)
## Base URL
```
http://backend-service:8000
```
## Authentication
All endpoints (except `/api/health`) require JWT token in Authorization header:
```
Authorization: Bearer <jwt_token>
```
## Endpoints
### Health Check
```
GET /api/health
```
**Response**: 200 OK
```json
{
"status": "healthy",
"version": "1.0.0"
}
```
---
### Create Todo
```
POST /api/todos
Authorization: Bearer <jwt_token>
Content-Type: application/json
{
"title": "Buy groceries",
"description": "Milk, eggs, bread",
"priority": "high"
}
```
**Response**: 201 Created
```json
{
"id": 1,
"title": "Buy groceries",
"description": "Milk, eggs, bread",
"priority": "high",
"completed": false,
"user_id": 123,
"created_at": "2026-01-30T00:00:00Z"
}
```
---
### List Todos
```
GET /api/todos
Authorization: Bearer <jwt_token>
```
**Response**: 200 OK
```json
{
"todos": [
{
"id": 1,
"title": "Buy groceries",
"description": "Milk, eggs, bread",
"priority": "high",
"completed": false,
"user_id": 123,
"created_at": "2026-01-30T00:00:00Z"
}
]
}
```
---
### Get Todo by ID
```
GET /api/todos/{id}
Authorization: Bearer <jwt_token>
```
**Response**: 200 OK
```json
{
"id": 1,
"title": "Buy groceries",
"description": "Milk, eggs, bread",
"priority": "high",
"completed": false,
"user_id": 123,
"created_at": "2026-01-30T00:00:00Z"
}
```
---
### Update Todo
```
PUT /api/todos/{id}
Authorization: Bearer <jwt_token>
Content-Type: application/json
{
"title": "Buy groceries",
"description": "Milk, eggs, bread, butter",
"priority": "high",
"completed": true
}
```
**Response**: 200 OK
```json
{
"id": 1,
"title": "Buy groceries",
"description": "Milk, eggs, bread, butter",
"priority": "high",
"completed": true,
"user_id": 123,
"updated_at": "2026-01-30T01:00:00Z"
}
```
---
### Delete Todo
```
DELETE /api/todos/{id}
Authorization: Bearer <jwt_token>
```
**Response**: 200 OK
```json
{
"message": "Todo deleted successfully"
}
```
---
## Error Responses
All error responses follow this format:
```json
{
"error": "Error message",
"detail": "Detailed error description"
}
```
**Common Status Codes**:
- 400 Bad Request - Invalid input
- 401 Unauthorized - Missing or invalid JWT token
- 403 Forbidden - User doesn't own this todo
- 404 Not Found - Todo doesn't exist
- 500 Internal Server Error - Server error
## Chatbot Integration Notes
1. **JWT Token Forwarding**: Chatbot MUST include user's JWT token when calling backend APIs
2. **User Isolation**: Backend automatically filters todos by `user_id` from JWT
3. **Intent Mapping**:
- "add/create/insert todo" → POST /api/todos
- "list/show/get todos" → GET /api/todos
- "update/edit/modify todo" → PUT /api/todos/{id}
- "delete/remove todo" → DELETE /api/todos/{id}
4. **Priority Values**: "low", "medium", "high"
5. **Boolean Fields**: `completed` is boolean (true/false)
## Phase IV Constraint
This API contract is **READ-ONLY**. No modifications allowed in Phase IV.
|