phase-4/docs/backend-api-contract.md

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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "message": "Todo deleted successfully"
}

---

Error Responses

All error responses follow this format:

{
  "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.