Todo API
e# Todo List API Documentation
Welcome to our state-of-the-art Todo List API documentation. This comprehensive guide will walk you through all available endpoints, authentication methods, data models, and integration examples.
## Table of Contents
- [Overview](#overview)
- [Authentication](#authentication)
- [API Architecture](#api-architecture)
- [Endpoints](#endpoints)
- [Todo Items](#todo-items)
- [Categories](#categories)
- [Users](#users)
- [Data Models](#data-models)
- [Error Handling](#error-handling)
- [Rate Limiting](#rate-limiting)
- [Webhooks](#webhooks)
- [SDK & Libraries](#sdk--libraries)
- [Examples](#examples)
## Overview
Our Todo List API allows developers to create, read, update, and delete todo items programmatically. The API follows REST principles and uses JSON for request and response formatting.
## Authentication
The API uses JWT (JSON Web Tokens) for authentication.
```mermaid
sequenceDiagram
participant Client
participant AuthService
participant API
Client->>AuthService: POST /auth/login with credentials
AuthService->>Client: Returns JWT token
Client->>API: API request with JWT in Authorization header
API->>API: Validate token
API->>Client: API response
```
### Authentication Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/auth/login` | POST | Authenticates user and returns JWT |
| `/auth/refresh` | POST | Refreshes an existing JWT |
| `/auth/logout` | POST | Invalidates JWT |
Example request:
```bash
curl -X POST https://api.todoapp.com/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]", "password": "secure_password"}'
```
Example response:
```json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_at": "2023-12-31T23:59:59Z",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
## API Architecture
The Todo List API is built with a microservices architecture as illustrated below:
```mermaid
graph TD
Client[Client Applications]
Gateway[API Gateway]
Auth[Auth Service]
Todo[Todo Service]
User[User Service]
Notif[Notification Service]
DB1[(Auth Database)]
DB2[(Todo Database)]
DB3[(User Database)]
Redis[(Redis Cache)]
Client <--> Gateway
Gateway <--> Auth
Gateway <--> Todo
Gateway <--> User
Gateway <--> Notif
Auth <--> DB1
Todo <--> DB2
Todo <--> Redis
User <--> DB3
Todo --> Notif
```
## Endpoints
### Todo Items
```mermaid
classDiagram
class TodoItem {
+string id
+string title
+string description
+boolean completed
+string category_id
+Date due_date
+Date created_at
+Date updated_at
}
```
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/todos` | GET | List all todo items |
| `/todos` | POST | Create a new todo item |
| `/todos/{id}` | GET | Retrieve a specific todo item |
| `/todos/{id}` | PUT | Update a todo item |
| `/todos/{id}` | PATCH | Partially update a todo item |
| `/todos/{id}` | DELETE | Delete a todo item |
| `/todos/batch` | POST | Batch create or update todos |
| `/todos/search` | GET | Search for todos with filters |
#### List Todo Items
```http
GET /todos?limit=20&offset=0&sort=due_date&order=asc&completed=false
```
Query Parameters:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of items to return (default: 20, max: 100) |
| `offset` | integer | No | Number of items to skip (default: 0) |
| `sort` | string | No | Field to sort by (created_at, due_date, title) |
| `order` | string | No | Sort order (asc, desc) |
| `completed` | boolean | No | Filter by completion status |
| `category_id` | string | No | Filter by category |
| `due_before` | string | No | ISO date to filter todos due before |
| `due_after` | string | No | ISO date to filter todos due after |
Response:
```json
{
"data": [
{
"id": "t-123456",
"title": "Complete API documentation",
"description": "Write comprehensive docs for the Todo API",
"completed": false,
"category_id": "c-tech",
"due_date": "2023-10-25T15:00:00Z",
"created_at": "2023-10-20T09:15:32Z",
"updated_at": "2023-10-20T09:15:32Z"
},
// More todo items...
],
"meta": {
"total": 42,
"limit": 20,
"offset": 0
},
"links": {
"self": "/todos?limit=20&offset=0",
"next": "/todos?limit=20&offset=20",
"prev": null
}
}
```
#### Create Todo Item
```http
POST /todos
```
Request body:
```json
{
"title": "Review project proposal",
"description": "Go through the project proposal and add comments",
"category_id": "c-work",
"due_date": "2023-10-26T12:00:00Z"
}
```
Response:
```json
{
"id": "t-789012",
"title": "Review project proposal",
"description": "Go through the project proposal and add comments",
"completed": false,
"category_id": "c-work",
"due_date": "2023-10-26T12:00:00Z",
"created_at": "2023-10-21T10:30:15Z",
"updated_at": "2023-10-21T10:30:15Z"
}
```
### Categories
```mermaid
classDiagram
class Category {
+string id
+string name
+string color
+string icon
+string user_id
+Date created_at
+Date updated_at
}
```
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/categories` | GET | List all categories |
| `/categories` | POST | Create a new category |
| `/categories/{id}` | GET | Retrieve a specific category |
| `/categories/{id}` | PUT | Update a category |
| `/categories/{id}` | DELETE | Delete a category |
| `/categories/{id}/todos` | GET | List all todos in a category |
### Users
```mermaid
classDiagram
class User {
+string id
+string email
+string name
+string avatar_url
+Date created_at
+Date updated_at
+Date last_login_at
}
```
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/users/me` | GET | Get current user profile |
| `/users/me` | PATCH | Update current user profile |
| `/users/me/settings` | GET | Get user settings |
| `/users/me/settings` | PATCH | Update user settings |
## Data Models
```mermaid
erDiagram
User ||--o{ Category : creates
User ||--o{ TodoItem : owns
Category ||--o{ TodoItem : contains
User {
string id PK
string email
string name
string password_hash
string avatar_url
datetime created_at
datetime updated_at
datetime last_login_at
}
Category {
string id PK
string name
string color
string icon
string user_id FK
datetime created_at
datetime updated_at
}
TodoItem {
string id PK
string title
string description
boolean completed
string category_id FK
string user_id FK
datetime due_date
datetime created_at
datetime updated_at
}
```
## Error Handling
The API uses conventional HTTP status codes to indicate success or failure of requests.
```mermaid
graph TD
A[API Request] --> B{Successful?}
B -->|Yes| C[2xx Success Response]
B -->|No| D{Error Type}
D -->|Client Error| E[4xx Client Error]
D -->|Server Error| F[5xx Server Error]
E --> G[Error Response]
F --> G
```
### Common Error Codes
| Code | Name | Description |
|------|------|-------------|
| 400 | Bad Request | The request was malformed or invalid |
| 401 | Unauthorized | Authentication is required |
| 403 | Forbidden | The authenticated user doesn't have permission |
| 404 | Not Found | The requested resource doesn't exist |
| 422 | Unprocessable Entity | The request data was valid but unprocessable |
| 429 | Too Many Requests | The user has sent too many requests |
| 500 | Internal Server Error | An unexpected server error occurred |
### Error Response Format
```json
{
"error": {
"code": "invalid_request",
"message": "The request was invalid",
"details": [
{
"field": "due_date",
"message": "Must be a valid ISO 8601 date"
}
]
}
}
```
## Rate Limiting
The API implements rate limiting to prevent abuse.
```mermaid
sequenceDiagram
participant Client
participant Gateway as API Gateway
participant RateLimit as Rate Limiter
participant API
Client->>Gateway: API Request
Gateway->>RateLimit: Check quota
alt Quota available
RateLimit->>Gateway: Allow request
Gateway->>API: Forward request
API->>Gateway: Response
Gateway->>Client: Return response with rate limit headers
else Quota exceeded
RateLimit->>Gateway: Reject request
Gateway->>Client: 429 Too Many Requests
end
```
Each API response includes headers for rate limiting:
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1635789600
```
## Webhooks
The API supports webhooks for real-time notifications.
```mermaid
sequenceDiagram
participant User
participant API
participant EventBus
participant WebhookService
participant ClientServer
User->>API: Update todo
API->>EventBus: Publish todo.updated event
EventBus->>WebhookService: Consume event
WebhookService->>ClientServer: POST webhook payload
ClientServer->>WebhookService: 200 OK
```
### Available Events
| Event | Description |
|-------|-------------|
| `todo.created` | A new todo item is created |
| `todo.updated` | A todo item is updated |
| `todo.deleted` | A todo item is deleted |
| `todo.completed` | A todo item is marked as completed |
| `category.created` | A new category is created |
| `category.updated` | A category is updated |
| `category.deleted` | A category is deleted |
### Webhook Configuration
To register a webhook:
```http
POST /webhooks
```
```json
{
"url": "https://example.com/webhook",
"events": ["todo.created", "todo.completed"],
"secret": "your_signing_secret"
}
```
## SDK & Libraries
We provide official SDKs for several programming languages:
```mermaid
flowchart LR
API[Todo API] --> JS[JavaScript SDK]
API --> PY[Python SDK]
API --> JV[Java SDK]
API --> GO[Go SDK]
API --> RB[Ruby SDK]
API --> PH[PHP SDK]
subgraph "Client Applications"
JS --> Web[Web Apps]
JS --> Node[Node.js Apps]
PY --> DS[Data Science]
PY --> Auto[Automation]
JV --> Android[Android Apps]
JV --> Enterprise[Enterprise Apps]
GO --> Cloud[Cloud Services]
RB --> Rails[Rails Apps]
PH --> Web2[Web Apps]
end
```
## Examples
### State Diagram for a Todo Item
```mermaid
stateDiagram-v2
[*] --> Created: Create todo
Created --> InProgress: Start working
Created --> Cancelled: Cancel todo
InProgress --> OnHold: Pause work
InProgress --> Completed: Finish todo
OnHold --> InProgress: Resume work
OnHold --> Cancelled: Cancel todo
Completed --> [*]
Cancelled --> [*]
```
### Task Completion Timeline
```mermaid
gantt
title Todo Item Lifecycle
dateFormat YYYY-MM-DD
section Planning
Create todo :a1, 2023-10-01, 1d
Define subtasks :a2, after a1, 2d
section Execution
Work on todo :a3, after a2, 5d
Review progress :a4, after a3, 1d
section Completion
Mark as completed :a5, after a4, 1d
Archive :a6, after a5, 1d
```
### Example Integration Flow
```mermaid
flowchart TD
A[Start] --> B{Already authenticated?}
B -->|Yes| C[Get todos]
B -->|No| D[Authenticate]
D --> C
C --> E{Any todos?}
E -->|Yes| F[Display todos]
E -->|No| G[Show empty state]
F --> H[User interaction]
G --> I[Create first todo]
H --> J{Action?}
J -->|Create| K[Add new todo]
J -->|Update| L[Modify todo]
J -->|Delete| M[Remove todo]
J -->|Complete| N[Mark as done]
K --> O[API request]
L --> O
M --> O
N --> O
O --> P[Update UI]
P --> H
I --> O
```
### Real-time Sync Example
```mermaid
sequenceDiagram
participant Client1 as User Device 1
participant Client2 as User Device 2
participant API
participant DB as Database
participant WS as WebSocket Server
Client1->>API: Update todo (PUT /todos/123)
API->>DB: Save changes
API->>WS: Broadcast update
API->>Client1: 200 OK Response
WS->>Client2: Push update event
Client2->>Client2: Update local state
```
---
This documentation provides a comprehensive overview of our Todo List API. For additional help, please contact our support team at [email protected].