task-engine-ai-core/assets/api-documentation-template.md

Revolutionary AI-driven task management system with complete transformation trilogy: Frontend v0.1.0, Backend v0.2.0, CLI v0.3.0 - Enterprise-grade performance with 95% improvements

# {{projectName}} - API Documentation

## Overview

This document provides comprehensive API documentation for {{projectName}}.

## Base URL

```
Development: http://localhost:3000/api
Staging: https://staging.{{projectNameLower}}.com/api
Production: https://api.{{projectNameLower}}.com
```

## Authentication

### API Key Authentication
```http
Authorization: Bearer YOUR_API_KEY
```

### JWT Authentication
```http
Authorization: Bearer YOUR_JWT_TOKEN
```

## Endpoints

### 1. Authentication

#### POST /auth/login
Login with credentials.

**Request:**
```json
{
  "email": "user@example.com",
  "password": "password123"
}
```

**Response:**
```json
{
  "success": true,
  "token": "jwt_token_here",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "User Name"
  }
}
```

#### POST /auth/register
Register a new user.

**Request:**
```json
{
  "name": "User Name",
  "email": "user@example.com",
  "password": "password123"
}
```

**Response:**
```json
{
  "success": true,
  "message": "User registered successfully",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "User Name"
  }
}
```

### 2. [Resource Name]

#### GET /[resource]
Get all [resource] items.

**Parameters:**
- `page` (optional): Page number (default: 1)
- `limit` (optional): Items per page (default: 10)
- `sort` (optional): Sort field (default: created_at)
- `order` (optional): Sort order (asc/desc, default: desc)

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Item Name",
      "description": "Item Description",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "pages": 10
  }
}
```

#### GET /[resource]/:id
Get a specific [resource] item.

**Response:**
```json
{
  "success": true,
  "data": {
    "id": 1,
    "name": "Item Name",
    "description": "Item Description",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

#### POST /[resource]
Create a new [resource] item.

**Request:**
```json
{
  "name": "Item Name",
  "description": "Item Description"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Item created successfully",
  "data": {
    "id": 1,
    "name": "Item Name",
    "description": "Item Description",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

#### PUT /[resource]/:id
Update a [resource] item.

**Request:**
```json
{
  "name": "Updated Item Name",
  "description": "Updated Item Description"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Item updated successfully",
  "data": {
    "id": 1,
    "name": "Updated Item Name",
    "description": "Updated Item Description",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  }
}
```

#### DELETE /[resource]/:id
Delete a [resource] item.

**Response:**
```json
{
  "success": true,
  "message": "Item deleted successfully"
}
```

## Error Responses

### 400 Bad Request
```json
{
  "success": false,
  "error": "Bad Request",
  "message": "Invalid request parameters",
  "details": {
    "field": "Field-specific error message"
  }
}
```

### 401 Unauthorized
```json
{
  "success": false,
  "error": "Unauthorized",
  "message": "Authentication required"
}
```

### 403 Forbidden
```json
{
  "success": false,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}
```

### 404 Not Found
```json
{
  "success": false,
  "error": "Not Found",
  "message": "Resource not found"
}
```

### 500 Internal Server Error
```json
{
  "success": false,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}
```

## Rate Limiting

- **Rate Limit:** 1000 requests per hour per API key
- **Headers:**
  - `X-RateLimit-Limit`: Request limit per hour
  - `X-RateLimit-Remaining`: Remaining requests in current window
  - `X-RateLimit-Reset`: Time when rate limit resets (Unix timestamp)

## SDKs and Libraries

### JavaScript/Node.js
```bash
npm install {{projectNameLower}}-sdk
```

### Python
```bash
pip install {{projectNameLower}}-sdk
```

### cURL Examples

#### Get all items
```bash
curl -X GET "https://api.{{projectNameLower}}.com/[resource]" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

#### Create new item
```bash
curl -X POST "https://api.{{projectNameLower}}.com/[resource]" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Item Name",
    "description": "Item Description"
  }'
```

## Changelog

### v1.0.0 ({{currentDateFormatted}})
- Initial API release
- Basic CRUD operations
- Authentication system

---

**Last Updated:** {{currentDateFormatted}}
**Author:** {{authorName}}
**Generated by Task Engine AI Core v{{taskEngineVersion}}**