README.md

metadata

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:

{
  "title": "Task title",
  "description": "Task description",
  "completed": false
}

Update a todo

PUT /api/todos/<id>

Requires authentication.

Request body:

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

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

docker build -t todo-api .

Running the Container Locally

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:

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:

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. Feel free to contribute and improve it!