API.md

# API Documentation

## REST API Endpoints

### Base URL
```
http://localhost:5000
```

### Authentication
Currently, the API is unauthenticated (for demo purposes).

---

## Endpoints

### 1. Generate Configuration

**Endpoint**: `POST /api/generate`

**Description**: Generate a complete application configuration from a natural language prompt.

**Request Body**:
```json
{
  "prompt": "Build a CRM with login, contacts, dashboard, and role-based access"
}
```

**Query Parameters**: None

**Headers**:
```
Content-Type: application/json
```

**Response (Success)**:
```json
{
  "success": true,
  "config": {
    "app_name": "CRM",
    "app_description": "...",
    "database_schema": [...],
    "api_schema": [...],
    "ui_schema": [...],
    "auth_config": {...},
    "roles": [...],
    "business_logic": {...}
  },
  "execution_log": {
    "timestamp": "2026-05-06T07:52:40.123456",
    "stages": {...}
  },
  "executable_report": {
    "is_executable": true,
    "errors": [],
    "warnings": [],
    "simulation_log": [...]
  },
  "is_executable": true
}
```

**Response (Error)**:
```json
{
  "success": false,
  "error": "Prompt is required"
}
```

**Status Codes**:
- `200`: Successful generation
- `400`: Bad request (invalid prompt)
- `500`: Server error

**Constraints**:
- Prompt length: max 2,000 characters
- Rate limit: None (local deployment)

**Example**:
```bash
curl -X POST http://localhost:5000/api/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Build a todo app with users, tasks, and sharing"}'
```

---

### 2. Validate Configuration

**Endpoint**: `POST /api/validate`

**Description**: Validate an existing configuration against schema rules.

**Request Body**:
```json
{
  "config": {
    "app_name": "MyApp",
    "app_description": "...",
    "database_schema": [...],
    ...
  }
}
```

**Response (Success)**:
```json
{
  "success": true,
  "is_executable": true,
  "report": {
    "is_executable": true,
    "errors": [],
    "warnings": [],
    "simulation_log": [
      "✓ Database table 'users' initialized",
      "✓ API endpoint 'GET /api/users' registered",
      ...
    ],
    "total_checks": 12
  }
}
```

**Response (Error)**:
```json
{
  "success": false,
  "error": "Internal server error"
}
```

**Status Codes**:
- `200`: Validation complete (executable or not)
- `400`: Bad request (invalid config)
- `500`: Server error

---

### 3. Get Recent Requests

**Endpoint**: `GET /api/recent`

**Description**: Get list of recent generation requests (last 10).

**Query Parameters**: None

**Response**:
```json
{
  "recent": [
    {
      "timestamp": "2026-05-06T07:52:40.123456",
      "prompt": "Build a CRM with login, contacts, dashboard...",
      "success": true,
      "executable": true
    },
    ...
  ]
}
```

**Status Codes**:
- `200`: Success

---

### 4. Get Example Generation

**Endpoint**: `GET /api/example`

**Description**: Get a pre-generated example configuration.

**Query Parameters**: None

**Response**:
```json
{
  "prompt": "Build a CRM with login, contacts, dashboard, role-based access...",
  "config": {...},
  "executable": true
}
```

**Status Codes**:
- `200`: Success

---

### 5. Health Check

**Endpoint**: `GET /api/health`

**Description**: Check if the API is running and get system status.

**Query Parameters**: None

**Response**:
```json
{
  "status": "healthy",
  "timestamp": "2026-05-06T07:52:40.123456",
  "total_requests": 15
}
```

**Status Codes**:
- `200`: Healthy
- `503`: Service unavailable

---

## Error Responses

### Common Error Codes

**400 - Bad Request**
```json
{
  "error": "Prompt is required"
}
```

**413 - Payload Too Large**
```json
{
  "error": "Prompt is too long (max 2000 chars)"
}
```

**404 - Not Found**
```json
{
  "error": "Not found"
}
```

**500 - Internal Server Error**
```json
{
  "error": "Internal server error"
}
```

---

## Configuration Object Format

### Top-Level Fields

```json
{
  "app_name": "string",
  "app_description": "string",
  "database_schema": [...],
  "api_schema": [...],
  "ui_schema": [...],
  "auth_config": {...},
  "roles": [...],
  "business_logic": {...},
  "validation_metadata": {...}
}
```

### Database Schema

```json
{
  "name": "users",
  "fields": [
    {
      "name": "id",
      "type": "string",
      "required": true,
      "description": "User ID"
    },
    {
      "name": "email",
      "type": "email",
      "required": true,
      "validation_rules": {
        "unique": true
      }
    }
  ],
  "primary_key": "id",
  "relations": {
    "role_id": "roles"
  },
  "indexes": ["id", "email"]
}
```

### API Schema

```json
{
  "path": "/api/users",
  "method": "GET",
  "description": "Get list of users",
  "request_body": {
    "page": {
      "name": "page",
      "type": "number",
      "required": false
    }
  },
  "response_body": {
    "users": {
      "name": "users",
      "type": "array",
      "required": true
    }
  },
  "required_role": "user",
  "validation_rules": ["Pagination required", "Min page size: 10"]
}
```

### UI Schema

```json
{
  "path": "/users",
  "title": "Users Page",
  "components": [
    {
      "name": "header",
      "type": "header"
    },
    {
      "name": "user-table",
      "type": "table",
      "fields": ["id", "name", "email", "role"]
    }
  ],
  "required_role": "user",
  "data_source": "/api/users"
}
```

### Auth Config

```json
{
  "type": "jwt",
  "secret_key": "your-secret-key",
  "expiry": 3600,
  "refresh_token_expiry": 86400,
  "algorithm": "HS256"
}
```

### Roles

```json
[
  {
    "name": "admin",
    "permissions": ["read_all", "write_all", "delete_all", "manage_users"],
    "description": "Administrator with full access"
  },
  {
    "name": "user",
    "permissions": ["read_own", "write_own", "delete_own"],
    "description": "Regular user with personal access"
  }
]
```

---

## Code Examples

### Python (requests)

```python
import requests
import json

# Generate configuration
response = requests.post(
    'http://localhost:5000/api/generate',
    json={
        'prompt': 'Build a CRM with contacts, dashboard, and analytics'
    }
)

config = response.json()

if config['success']:
    print(f"Generated: {config['config']['app_name']}")
    print(f"Executable: {config['is_executable']}")
    print(json.dumps(config['config'], indent=2))
```

### JavaScript (fetch)

```javascript
const prompt = "Build a CRM with contacts, dashboard, and analytics";

const response = await fetch('http://localhost:5000/api/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ prompt })
});

const data = await response.json();

if (data.success) {
  console.log('Generated:', data.config.app_name);
  console.log('Executable:', data.is_executable);
  console.log(JSON.stringify(data.config, null, 2));
}
```

### cURL

```bash
# Generate config
curl -X POST http://localhost:5000/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Build a CRM with contacts, dashboard, and analytics"
  }' | jq .

# Health check
curl http://localhost:5000/api/health | jq .

# Get recent requests
curl http://localhost:5000/api/recent | jq .

# Get example
curl http://localhost:5000/api/example | jq .
```

---

## Rate Limiting

Currently disabled. For production deployment, implement:
- 100 requests/minute per IP
- 10,000 requests/day per API key
- Exponential backoff on rate limit errors (429)

---

## Webhooks (Future)

Support for event notifications:
- `generation.started`
- `generation.completed`
- `generation.failed`
- `validation.warning`

---

## Version History

### v1.0 (Current)
- Basic generation pipeline
- Validation and repair
- REST API
- Web interface

### v1.1 (Planned)
- Advanced LLM selection
- Extended schema types
- Webhook support
- Rate limiting

### v2.0 (Future)
- Direct app scaffolding
- Framework selection
- Deployment integration

---

## Support

For API issues or questions:
1. Check ARCHITECTURE.md for system design
2. Review quickstart.py for examples
3. Run evaluation framework for diagnostics
4. Check execution logs in API responses