Skip to content

IMPLEMENTATION.md

Latest commit

 

History

History
141 lines (115 loc) · 4.34 KB

IMPLEMENTATION.md

File metadata and controls

141 lines (115 loc) · 4.34 KB

Taskwarrior API - Implementation Summary

What Was Built

A complete headless REST API server for Taskwarrior in Go with:

Core Features

  • ✅ Full CRUD operations for tasks
  • ✅ Task lifecycle operations (start, stop, done)
  • ✅ Report endpoints (next, active, completed, waiting, all)
  • ✅ Project management
  • ✅ Token-based authentication
  • ✅ CORS support
  • ✅ Interactive Swagger UI documentation
  • ✅ Environment variable configuration
  • ✅ Graceful shutdown
  • ✅ Request logging

Technology Stack

  • Language: Go 1.21+
  • Web Framework: Gin
  • API Documentation: Swagger/OpenAPI
  • Configuration: Environment variables only
  • Integration: Taskwarrior CLI (no direct file access)

Project Structure

taskwarrior-api/
├── cmd/server/main.go          # Server entry point with Swagger metadata
├── internal/
│   ├── api/
│   │   ├── router.go           # Routes and middleware setup
│   │   ├── handlers/
│   │   │   ├── tasks.go        # Task CRUD + lifecycle operations
│   │   │   ├── reports.go      # Report endpoints
│   │   │   └── projects.go     # Project endpoints
│   │   └── middleware/
│   │       ├── auth.go         # Bearer token authentication
│   │       └── logging.go      # Request logging
│   ├── taskwarrior/
│   │   ├── types.go            # Task models + custom time parsing
│   │   ├── client.go           # CLI wrapper
│   │   └── parser.go           # Filtering and validation
│   ├── config/config.go        # Environment variable configuration
│   └── auth/token.go           # Token validation
├── docs/                       # Auto-generated Swagger docs
├── Makefile                    # Build automation
├── env.example                 # Configuration template
├── go.mod & go.sum            # Dependencies
└── README.md                   # Complete documentation

API Endpoints

Tasks

  • GET /api/v1/tasks - List tasks with filters
  • GET /api/v1/tasks/:uuid - Get single task
  • POST /api/v1/tasks - Create task
  • PATCH /api/v1/tasks/:uuid - Update task
  • DELETE /api/v1/tasks/:uuid - Delete task
  • POST /api/v1/tasks/:uuid/done - Mark as complete
  • POST /api/v1/tasks/:uuid/start - Start timer
  • POST /api/v1/tasks/:uuid/stop - Stop timer

Reports

  • GET /api/v1/reports/next - Pending by urgency
  • GET /api/v1/reports/active - Started tasks
  • GET /api/v1/reports/completed - Completed tasks
  • GET /api/v1/reports/waiting - Waiting tasks
  • GET /api/v1/reports/all - All tasks

Projects

  • GET /api/v1/projects - List projects with counts
  • GET /api/v1/projects/:name/tasks - Tasks in project

Documentation

  • GET /swagger/index.html - Interactive Swagger UI
  • GET /health - Health check (no auth)

Key Implementation Details

Taskwarrior Integration

  • Uses CLI exclusively (task export, task add, etc.)
  • Never directly touches .task/ files
  • Custom time parser for Taskwarrior's 20060102T150405Z format
  • Returns dates only (YYYY-MM-DD) in API responses
  • Input sanitization to prevent command injection

Authentication

  • Simple bearer token validation
  • Multiple tokens supported (comma-separated)
  • All endpoints except /health and /swagger/* require auth

Configuration

  • Environment variables only (no config files)
  • Required: TW_API_TOKENS
  • Optional: host, port, data location, CORS, log level
  • See env.example for template

Error Handling

  • Consistent JSON error format with error codes
  • Proper HTTP status codes
  • Detailed logging for debugging

Usage

Start Server

export TW_API_TOKENS="your-token"
make run

Access Swagger UI

http://localhost:8080/swagger/index.html

Example API Call

curl -H "Authorization: Bearer your-token" \
  http://localhost:8080/api/v1/tasks

Development Commands

make install        # Install dependencies + swag CLI
make build          # Build binary (auto-generates Swagger docs)
make run            # Run server
make swagger        # Generate Swagger docs only
make test           # Run tests
make clean          # Clean build artifacts

Status

🚧 Under Construction - Not production-ready

The server is functional but still in active development. APIs may change.