| --- |
| title: ToDo API |
| emoji: 📝 |
| colorFrom: blue |
| colorTo: green |
| sdk: docker |
| license: gpl-3.0 |
| pinned: false |
| app_port: 5000 |
| --- |
| |
| The table above contains the configuration for the Huggingface Space. |
| Just ignore it. |
|
|
| # Simple ToDo API |
|
|
| A simple RESTful API for managing todo items built with Python and Flask. |
|
|
| ## Setup |
|
|
| 1. Create a virtual environment: |
| ``` |
| python -m venv venv |
| ``` |
|
|
| 2. Activate the virtual environment: |
| - Windows: `venv\Scripts\activate` |
| - Unix/MacOS: `source venv/bin/activate` |
|
|
| 3. Install dependencies: |
| ``` |
| pip install -r requirements.txt |
| ``` |
|
|
| 4. Set the environment variables: |
| - Required: |
| - Windows: `set TODO_TOKEN=your_secret_token` |
| - Unix/MacOS: `export TODO_TOKEN=your_secret_token` |
|
|
| - Optional: |
| - Windows: |
| ``` |
| set PAGE_TITLE=Your Custom Title |
| set SHOW_ADMIN_PANEL_BUTTON=true |
| set DEBUG_MODE=false |
| ``` |
| - Unix/MacOS: |
| ``` |
| export PAGE_TITLE="Your Custom Title" |
| export SHOW_ADMIN_PANEL_BUTTON=true |
| export DEBUG_MODE=false |
| ``` |
| |
| 5. Run the application: |
| ``` |
| python app.py |
| ``` |
|
|
| The API will be available at `http://127.0.0.1:5000`. |
|
|
| ## Environment Variables |
|
|
| The application supports the following environment variables: |
|
|
| | Variable | Description | Default Value | Required | |
| |----------|-------------|---------------|----------| |
| | `TODO_TOKEN` | Authentication token for API access | None | Yes | |
| | `PAGE_TITLE` | Custom title for the application | "ToDo App" | No | |
| | `SHOW_ADMIN_PANEL_BUTTON` | Whether to show the admin panel button on the home page | "true" | No | |
| | `DEBUG_MODE` | Enable Flask debug mode with auto-reloading and detailed error pages | "false" | No | |
|
|
| Note: For boolean environment variables like `SHOW_ADMIN_PANEL_BUTTON`, the values "true", "yes", "1", "y" (case-insensitive) are considered true. Any other value is considered false. |
|
|
| ## Authentication |
|
|
| The API uses two levels of authentication: |
|
|
| 1. **Guest Access (Default Mode)**: |
| - Guests can read todos (GET operations) without authentication |
| - All write operations (POST, PUT, DELETE) require authentication |
|
|
| 2. **Private Mode**: |
| - When enabled, all operations (including GET) require authentication |
| - This mode can be toggled by authenticated users |
|
|
| Authentication is done using a Bearer token in the Authorization header: |
|
|
| ``` |
| Authorization: Bearer your_secret_token |
| ``` |
|
|
| The token must match the value set in the `TODO_TOKEN` environment variable. |
|
|
| ## Data Persistence |
|
|
| The application stores all data in JSON files located in the `data` directory: |
|
|
| - `todos.json`: Contains all todo items and the next ID counter |
| - `settings.json`: Contains application settings like private mode status |
|
|
| Data is automatically saved to these files whenever: |
| - A new todo is created |
| - A todo is updated |
| - A todo is deleted |
| - Private mode is toggled |
|
|
| This ensures that your data persists between application restarts. |
|
|
| The application also includes an automatic file repair mechanism that: |
| - Detects corrupted or empty JSON files on startup |
| - Creates new valid files with default values if needed |
| - Ensures the application can start even if data files are damaged |
|
|
| ## Web Interface |
|
|
| The application provides two interfaces: |
|
|
| ### Public View (`/`) |
| - View all todos (read-only) |
| - Link to admin panel |
|
|
| ### Admin Panel (`/admin/`) |
| - Requires authentication with a valid token |
| - Add new todos |
| - Mark todos as completed |
| - Delete todos |
| - Toggle Private Mode |
| - Export todos as JSON file |
|
|
| ## API Endpoints |
|
|
| ### Get all todos |
| ``` |
| GET /api/todos |
| ``` |
| Requires authentication in private mode. |
|
|
| ### Get a specific todo |
| ``` |
| GET /api/todos/<id> |
| ``` |
| Requires authentication in private mode. |
|
|
| ### Create a new todo |
| ``` |
| POST /api/todos |
| ``` |
| Requires authentication. |
|
|
| Request body: |
| ```json |
| { |
| "title": "Task title", |
| "description": "Task description", |
| "completed": false |
| } |
| ``` |
|
|
| ### Update a todo |
| ``` |
| PUT /api/todos/<id> |
| ``` |
| Requires authentication. |
|
|
| Request body: |
| ```json |
| { |
| "title": "Updated title", |
| "description": "Updated description", |
| "completed": true |
| } |
| ``` |
|
|
| ### Delete a todo |
| ``` |
| DELETE /api/todos/<id> |
| ``` |
| Requires authentication. |
|
|
| ### Get Private Mode status |
| ``` |
| GET /api/private-mode |
| ``` |
| No authentication required. |
|
|
| ### Toggle Private Mode |
| ``` |
| POST /api/private-mode |
| ``` |
| Requires authentication. |
|
|
| Request body: |
| ```json |
| { |
| "enabled": true |
| } |
| ``` |
|
|
| ### Export Todos as JSON |
| ``` |
| GET /api/todos/export |
| ``` |
| Requires authentication. |
|
|
| Returns a downloadable JSON file containing all todos with additional metadata. The response includes: |
| - Content-Disposition header for browser download |
| - Content-Type: application/json |
| - A JSON object with todos, next_id, exported_at timestamp, and count fields |
|
|
| ## Example API Calls |
|
|
| ### Reading todos (Guest Access) |
| ``` |
| curl -X GET http://127.0.0.1:5000/api/todos |
| ``` |
|
|
| ### Reading todos (with Authentication) |
| ``` |
| curl -X GET http://127.0.0.1:5000/api/todos -H "Authorization: Bearer your_secret_token" |
| ``` |
|
|
| ### Creating a todo (Always requires authentication) |
| ``` |
| curl -X POST http://127.0.0.1:5000/api/todos -H "Content-Type: application/json" -H "Authorization: Bearer your_secret_token" -d '{"title": "New Task"}' |
| ``` |
|
|
| ### Checking Private Mode status |
| ``` |
| curl -X GET http://127.0.0.1:5000/api/private-mode |
| ``` |
|
|
| ### Enabling Private Mode |
| ``` |
| curl -X POST http://127.0.0.1:5000/api/private-mode -H "Content-Type: application/json" -H "Authorization: Bearer your_secret_token" -d '{"enabled": true}' |
| ``` |
|
|
| ### Exporting Todos as JSON |
| ``` |
| curl -X GET http://127.0.0.1:5000/api/todos/export -H "Authorization: Bearer your_secret_token" -o todos_export.json |
| ``` |
|
|
| ### Using PowerShell |
| ``` |
| # Get todos (Guest Access) |
| Invoke-RestMethod -Uri 'http://127.0.0.1:5000/api/todos' -Method Get |
| |
| # Get todos (with Authentication) |
| Invoke-RestMethod -Uri 'http://127.0.0.1:5000/api/todos' -Method Get -Headers @{Authorization = "Bearer your_secret_token"} |
| |
| # Check Private Mode status (no authentication required) |
| Invoke-RestMethod -Uri 'http://127.0.0.1:5000/api/private-mode' -Method Get |
| |
| # Create a todo |
| $body = @{ title = 'New Task' } | ConvertTo-Json |
| Invoke-RestMethod -Uri 'http://127.0.0.1:5000/api/todos' -Method Post -Body $body -ContentType 'application/json' -Headers @{Authorization = "Bearer your_secret_token"} |
| |
| # Enable Private Mode |
| $body = @{ enabled = $true } | ConvertTo-Json |
| Invoke-RestMethod -Uri 'http://127.0.0.1:5000/api/private-mode' -Method Post -Body $body -ContentType 'application/json' -Headers @{Authorization = "Bearer your_secret_token"} |
| |
| # Export Todos as JSON |
| Invoke-RestMethod -Uri 'http://127.0.0.1:5000/api/todos/export' -Method Get -Headers @{Authorization = "Bearer your_secret_token"} -OutFile 'todos_export.json' |
| ``` |
|
|
| ## Docker Support |
|
|
| This project includes Docker support for easy deployment on various platforms. The Dockerfile uses Ubuntu 22.04 as the base image and clones the repository during the build process, ensuring a lightweight and up-to-date deployment. |
|
|
| ### Building the Docker Image Locally |
|
|
| ```bash |
| docker build -t todo-api . |
| ``` |
|
|
| ### Running the Container Locally |
|
|
| ```bash |
| docker run -p 5000:5000 -e TODO_TOKEN=your_secret_token todo-api |
| ``` |
|
|
| ### Using Environment Variables |
|
|
| You can pass environment variables to customize the application: |
|
|
| ```bash |
| docker run -p 5000:5000 \ |
| -e TODO_TOKEN=your_secret_token \ |
| -e PAGE_TITLE="My Custom ToDo App" \ |
| -e SHOW_ADMIN_PANEL_BUTTON=true \ |
| -e DEBUG_MODE=false \ |
| todo-api |
| ``` |
|
|
| ### Persisting Data |
|
|
| To persist data between container restarts, mount a volume to the `/app/data` directory: |
|
|
| ```bash |
| docker run -p 5000:5000 \ |
| -e TODO_TOKEN=your_secret_token \ |
| -v $(pwd)/data:/app/data \ |
| todo-api |
| ``` |
|
|
| ## Open Source |
|
|
| This project is open source and available under the [GNU GPLv3 License](LICENSE). Feel free to contribute and improve it! |
