# Personal Internet Cell API Documentation

## Overview

The Personal Internet Cell API provides a comprehensive REST interface for managing all aspects of a personal internet cell, including network services, VPN management, email/calendar/file services, routing, and security features.

**Base URL**: `http://localhost:3000/api`  
**Content-Type**: `application/json`  
**Authentication**: Currently supports local access only (127.0.0.1, ::1, localhost)

## Table of Contents

1. [Authentication](#authentication)
2. [Error Handling](#error-handling)
3. [Health & Status](#health--status)
4. [Configuration Management](#configuration-management)
5. [Network Services](#network-services)
6. [WireGuard VPN](#wireguard-vpn)
7. [Peer Management](#peer-management)
8. [Email Services](#email-services)
9. [Calendar Services](#calendar-services)
10. [File Services](#file-services)
11. [Routing Services](#routing-services)
12. [Vault & Security](#vault--security)
13. [Container Management](#container-management)
14. [Logging & Monitoring](#logging--monitoring)

## Authentication

Currently, the API only accepts requests from localhost for security reasons. All endpoints require the client to be running on the same machine as the API server.

```bash
# Valid client IPs
127.0.0.1
::1
localhost
```

## Error Handling

All API endpoints return consistent error responses:

```json
{
  "error": "Error description",
  "timestamp": "2024-01-01T12:00:00Z",
  "service": "service_name"
}
```

Common HTTP status codes:
- `200` - Success
- `400` - Bad Request (invalid parameters)
- `403` - Forbidden (access denied)
- `404` - Not Found
- `500` - Internal Server Error

## Health & Status

### Get Cell Status

**GET** `/status`

Returns overall cell status including all services.

**Response:**
```json
{
  "cell_name": "personal-internet-cell",
  "domain": "cell.local",
  "uptime": 3600,
  "peers_count": 5,
  "services": {
    "network": {
      "running": true,
      "status": "online"
    },
    "wireguard": {
      "running": true,
      "status": "online"
    },
    "email": {
      "running": true,
      "status": "online"
    },
    "calendar": {
      "running": true,
      "status": "online"
    },
    "files": {
      "running": true,
      "status": "online"
    }
  },
  "timestamp": "2024-01-01T12:00:00Z"
}
```

### Health Check

**GET** `/health`

Simple health check endpoint.

**Response:**
```json
{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00Z",
  "version": "1.0.0"
}
```

### Get All Services Status

**GET** `/services/status`

Returns detailed status of all services.

**Response:**
```json
{
  "network": {
    "running": true,
    "status": "online",
    "dns_running": true,
    "dhcp_running": true,
    "ntp_running": true
  },
  "wireguard": {
    "running": true,
    "status": "online",
    "peers_count": 5
  },
  "email": {
    "running": true,
    "status": "online",
    "users_count": 3
  },
  "calendar": {
    "running": true,
    "status": "online",
    "calendars_count": 2
  },
  "files": {
    "running": true,
    "status": "online",
    "storage_used": "1.2GB"
  },
  "routing": {
    "running": true,
    "status": "online",
    "nat_rules_count": 3
  },
  "vault": {
    "running": true,
    "status": "online",
    "ca_configured": true,
    "certificates_count": 5
  },
  "timestamp": "2024-01-01T12:00:00Z"
}
```

## Configuration Management

### Get Configuration

**GET** `/config`

Returns current cell configuration.

**Response:**
```json
{
  "cell_name": "personal-internet-cell",
  "domain": "cell.local",
  "ip_range": "10.0.0.0/24",
  "wireguard_port": 51820,
  "dns_port": 53,
  "dhcp_range": "10.0.0.100-10.0.0.200"
}
```

### Update Configuration

**PUT** `/config`

Update cell configuration.

**Request:**
```json
{
  "cell_name": "my-cell",
  "domain": "mycell.local",
  "ip_range": "192.168.1.0/24"
}
```

**Response:**
```json
{
  "message": "Configuration updated successfully"
}
```

## Network Services

### Get DNS Records

**GET** `/dns/records`

Returns all DNS records.

**Response:**
```json
[
  {
    "name": "www",
    "type": "A",
    "value": "10.0.0.10",
    "ttl": 3600
  },
  {
    "name": "mail",
    "type": "CNAME",
    "value": "www",
    "ttl": 3600
  }
]
```

### Add DNS Record

**POST** `/dns/records`

Add a new DNS record.

**Request:**
```json
{
  "zone": "cell.local",
  "name": "api",
  "type": "A",
  "value": "10.0.0.5",
  "ttl": 3600
}
```

### Get DHCP Leases

**GET** `/dhcp/leases`

Returns current DHCP leases.

**Response:**
```json
[
  {
    "mac": "00:11:22:33:44:55",
    "ip": "10.0.0.100",
    "hostname": "laptop",
    "timestamp": "2024-01-01T10:00:00Z"
  }
]
```

### Add DHCP Reservation

**POST** `/dhcp/reservations`

Add a DHCP reservation.

**Request:**
```json
{
  "mac": "00:11:22:33:44:55",
  "ip": "10.0.0.50",
  "hostname": "server"
}
```

### Get Network Info

**GET** `/network/info`

Returns detailed network information.

**Response:**
```json
{
  "interfaces": [
    {
      "name": "eth0",
      "ip": "192.168.1.100",
      "mac": "00:11:22:33:44:55",
      "status": "up"
    }
  ],
  "gateway": "192.168.1.1",
  "dns_servers": ["8.8.8.8", "1.1.1.1"],
  "routing_table": [
    {
      "destination": "0.0.0.0/0",
      "gateway": "192.168.1.1",
      "interface": "eth0"
    }
  ]
}
```

### Get DNS Status

**GET** `/dns/status`

Returns DNS service status.

**Response:**
```json
{
  "running": true,
  "status": "online",
  "zones_count": 2,
  "records_count": 15,
  "queries_per_second": 25.5,
  "cache_hit_rate": 0.85
}
```

### Get NTP Status

**GET** `/ntp/status`

Returns NTP service status.

**Response:**
```json
{
  "running": true,
  "status": "online",
  "synchronized": true,
  "stratum": 3,
  "reference_id": "192.168.1.1",
  "offset": 0.001234
}
```

## WireGuard VPN

### Get WireGuard Status

**GET** `/wireguard/status`

Returns WireGuard service status.

**Response:**
```json
{
  "running": true,
  "status": "online",
  "interface": "wg0",
  "peers_count": 5,
  "total_traffic": {
    "bytes_sent": 1048576,
    "bytes_received": 2097152
  }
}
```

### Get WireGuard Peers

**GET** `/wireguard/peers`

Returns all WireGuard peers.

**Response:**
```json
[
  {
    "name": "alice",
    "public_key": "abc123...",
    "ip": "10.0.0.2",
    "allowed_ips": "10.0.0.2/32",
    "last_handshake": "2024-01-01T12:00:00Z",
    "transfer_rx": 1048576,
    "transfer_tx": 2097152
  }
]
```

### Add WireGuard Peer

**POST** `/wireguard/peers`

Add a new WireGuard peer.

**Request:**
```json
{
  "name": "bob",
  "public_key": "def456...",
  "ip": "10.0.0.3",
  "allowed_ips": "10.0.0.3/32"
}
```

### Generate Peer Keys

**POST** `/wireguard/keys/peer`

Generate new WireGuard keys for a peer.

**Request:**
```json
{
  "peer_name": "charlie"
}
```

**Response:**
```json
{
  "private_key": "private_key_here",
  "public_key": "public_key_here",
  "peer_name": "charlie"
}
```

## Peer Management

### Get All Peers

**GET** `/peers`

Returns all registered peers.

**Response:**
```json
[
  {
    "name": "alice",
    "ip": "10.0.0.2",
    "public_key": "abc123...",
    "added_at": "2024-01-01T10:00:00Z"
  }
]
```

### Add Peer

**POST** `/peers`

Add a new peer to the registry.

**Request:**
```json
{
  "name": "bob",
  "ip": "10.0.0.3",
  "public_key": "def456..."
}
```

**Response:**
```json
{
  "message": "Peer bob added successfully"
}
```

### Remove Peer

**DELETE** `/peers/{peer_name}`

Remove a peer from the registry.

**Response:**
```json
{
  "message": "Peer bob removed successfully"
}
```

### Update Peer IP

**PUT** `/peers/{peer_name}/update-ip`

Update a peer's IP address.

**Request:**
```json
{
  "ip": "10.0.0.4"
}
```

## Email Services

### Get Email Status

**GET** `/email/status`

Returns email service status.

**Response:**
```json
{
  "running": true,
  "status": "online",
  "smtp_running": true,
  "imap_running": true,
  "users_count": 3,
  "domain": "cell.local"
}
```

### Get Email Users

**GET** `/email/users`

Returns all email users.

**Response:**
```json
[
  {
    "username": "alice",
    "domain": "cell.local",
    "email": "alice@cell.local",
    "created_at": "2024-01-01T10:00:00Z"
  }
]
```

### Create Email User

**POST** `/email/users`

Create a new email user.

**Request:**
```json
{
  "username": "bob",
  "domain": "cell.local",
  "password": "secure_password"
}
```

### Delete Email User

**DELETE** `/email/users/{username}`

Delete an email user.

**Response:**
```json
{
  "message": "User bob deleted successfully"
}
```

### Send Email

**POST** `/email/send`

Send an email.

**Request:**
```json
{
  "from_email": "alice@cell.local",
  "to_email": "bob@cell.local",
  "subject": "Hello",
  "body": "This is a test email",
  "html_body": "<p>This is a test email</p>"
}
```

## Calendar Services

### Get Calendar Status

**GET** `/calendar/status`

Returns calendar service status.

**Response:**
```json
{
  "running": true,
  "status": "online",
  "users_count": 2,
  "calendars_count": 4,
  "events_count": 25
}
```

### Get Calendar Users

**GET** `/calendar/users`

Returns all calendar users.

**Response:**
```json
[
  {
    "username": "alice",
    "calendars_count": 2,
    "events_count": 15
  }
]
```

### Create Calendar User

**POST** `/calendar/users`

Create a new calendar user.

**Request:**
```json
{
  "username": "bob",
  "password": "secure_password"
}
```

### Create Calendar

**POST** `/calendar/calendars`

Create a new calendar.

**Request:**
```json
{
  "username": "alice",
  "calendar_name": "Work",
  "description": "Work calendar"
}
```

### Get Calendar Events

**GET** `/calendar/events/{username}/{calendar_name}`

Returns calendar events.

**Query Parameters:**
- `start_date`: Start date (YYYY-MM-DD)
- `end_date`: End date (YYYY-MM-DD)

**Response:**
```json
[
  {
    "id": "event_1",
    "title": "Meeting",
    "start": "2024-01-01T10:00:00Z",
    "end": "2024-01-01T11:00:00Z",
    "description": "Team meeting"
  }
]
```

## File Services

### Get File Status

**GET** `/files/status`

Returns file service status.

**Response:**
```json
{
  "running": true,
  "status": "online",
  "users_count": 3,
  "total_storage": "100GB",
  "used_storage": "25GB"
}
```

### Get File Users

**GET** `/files/users`

Returns all file storage users.

**Response:**
```json
[
  {
    "username": "alice",
    "storage_used": "5GB",
    "files_count": 150
  }
]
```

### Create File User

**POST** `/files/users`

Create a new file storage user.

**Request:**
```json
{
  "username": "bob",
  "password": "secure_password",
  "quota": "10GB"
}
```

### List Files

**GET** `/files/list/{username}`

List files for a user.

**Query Parameters:**
- `folder`: Folder path (optional)

**Response:**
```json
[
  {
    "name": "document.pdf",
    "path": "/documents/document.pdf",
    "size": 1048576,
    "modified": "2024-01-01T10:00:00Z",
    "type": "file"
  },
  {
    "name": "documents",
    "path": "/documents",
    "type": "folder"
  }
]
```

### Upload File

**POST** `/files/upload/{username}`

Upload a file.

**Request:** Multipart form data
- `file`: File to upload
- `path`: Destination path (optional)

### Download File

**GET** `/files/download/{username}/{file_path}`

Download a file.

**Response:** File content

## Routing Services

### Get Routing Status

**GET** `/routing/status`

Returns routing service status.

**Response:**
```json
{
  "running": true,
  "status": "online",
  "nat_enabled": true,
  "firewall_enabled": true,
  "nat_rules_count": 3,
  "firewall_rules_count": 10,
  "peer_routes_count": 5
}
```

### Get NAT Rules

**GET** `/routing/nat`

Returns all NAT rules.

**Response:**
```json
{
  "nat_rules": [
    {
      "id": "rule_1",
      "source_network": "10.0.0.0/24",
      "target_interface": "eth0",
      "masquerade": true,
      "nat_type": "MASQUERADE",
      "protocol": "ALL"
    }
  ]
}
```

### Add NAT Rule

**POST** `/routing/nat`

Add a new NAT rule.

**Request:**
```json
{
  "source_network": "10.0.0.0/24",
  "target_interface": "eth0",
  "masquerade": true,
  "nat_type": "MASQUERADE",
  "protocol": "ALL"
}
```

### Get Firewall Rules

**GET** `/routing/firewall`

Returns all firewall rules.

**Response:**
```json
{
  "firewall_rules": [
    {
      "id": "rule_1",
      "rule_type": "INPUT",
      "source": "0.0.0.0/0",
      "destination": "10.0.0.0/24",
      "action": "ACCEPT",
      "protocol": "TCP",
      "port": "22"
    }
  ]
}
```

### Add Firewall Rule

**POST** `/routing/firewall`

Add a new firewall rule.

**Request:**
```json
{
  "rule_type": "INPUT",
  "source": "0.0.0.0/0",
  "destination": "10.0.0.0/24",
  "action": "ACCEPT",
  "protocol": "TCP",
  "port": "22"
}
```

### Get Peer Routes

**GET** `/routing/peers`

Returns all peer routes.

**Response:**
```json
{
  "peer_routes": [
    {
      "peer_name": "alice",
      "peer_ip": "10.0.0.2",
      "allowed_networks": ["192.168.1.0/24"],
      "route_type": "split"
    }
  ]
}
```

### Add Peer Route

**POST** `/routing/peers`

Add a new peer route.

**Request:**
```json
{
  "peer_name": "bob",
  "peer_ip": "10.0.0.3",
  "allowed_networks": ["192.168.2.0/24"],
  "route_type": "bridge"
}
```

## Vault & Security

### Get Vault Status

**GET** `/vault/status`

Returns vault service status.

**Response:**
```json
{
  "ca_configured": true,
  "age_configured": true,
  "fernet_configured": true,
  "certificates_count": 5,
  "trusted_keys_count": 3,
  "trust_chains_count": 2
}
```

### Get Certificates

**GET** `/vault/certificates`

Returns all certificates.

**Response:**
```json
[
  {
    "common_name": "api.cell.local",
    "domains": ["api.cell.local", "www.cell.local"],
    "created": "2024-01-01T10:00:00Z",
    "expires": "2025-01-01T10:00:00Z",
    "status": "valid"
  }
]
```

### Generate Certificate

**POST** `/vault/certificates`

Generate a new certificate.

**Request:**
```json
{
  "common_name": "mail.cell.local",
  "domains": ["mail.cell.local", "smtp.cell.local"],
  "key_size": 2048,
  "days": 365
}
```

### Get CA Certificate

**GET** `/vault/ca/certificate`

Returns the CA certificate.

**Response:**
```json
{
  "certificate": "-----BEGIN CERTIFICATE-----\n..."
}
```

### Get Trusted Keys

**GET** `/vault/trust/keys`

Returns all trusted keys.

**Response:**
```json
[
  {
    "name": "alice",
    "public_key": "age1...",
    "trust_level": "direct",
    "added_at": "2024-01-01T10:00:00Z"
  }
]
```

### Add Trusted Key

**POST** `/vault/trust/keys`

Add a new trusted key.

**Request:**
```json
{
  "name": "bob",
  "public_key": "age1...",
  "trust_level": "direct"
}
```

## Container Management

### List Containers

**GET** `/containers`

Returns all containers.

**Response:**
```json
[
  {
    "id": "abc123",
    "name": "cell-api",
    "status": "running",
    "image": "personalinternetcell-api:latest",
    "labels": {}
  }
]
```

### Start Container

**POST** `/containers/{name}/start`

Start a container.

**Response:**
```json
{
  "started": true
}
```

### Stop Container

**POST** `/containers/{name}/stop`

Stop a container.

**Response:**
```json
{
  "stopped": true
}
```

### Restart Container

**POST** `/containers/{name}/restart`

Restart a container.

**Response:**
```json
{
  "restarted": true
}
```

### Get Container Logs

**GET** `/containers/{name}/logs`

Returns container logs.

**Query Parameters:**
- `tail`: Number of lines to return (default: 100)

**Response:**
```json
{
  "logs": "Container log output..."
}
```

### Get Container Stats

**GET** `/containers/{name}/stats`

Returns container statistics.

**Response:**
```json
{
  "cpu_usage": 2.5,
  "memory_usage": "512MB",
  "network_rx": 1048576,
  "network_tx": 2097152,
  "disk_usage": "1GB"
}
```

## Logging & Monitoring

### Get Backend Logs

**GET** `/logs`

Returns backend log file contents.

**Query Parameters:**
- `lines`: Number of lines to return (default: 100)

**Response:**
```json
{
  "log": "Log file contents..."
}
```

### Get Health History

**GET** `/health/history`

Returns recent health check results.

**Response:**
```json
[
  {
    "timestamp": "2024-01-01T12:00:00Z",
    "network": {"status": "online"},
    "wireguard": {"status": "online"},
    "email": {"status": "online"},
    "calendar": {"status": "online"},
    "files": {"status": "online"},
    "routing": {"status": "online"},
    "vault": {"status": "online"},
    "alerts": []
  }
]
```

## Usage Examples

### Python Client Example

```python
import requests

API_BASE = "http://localhost:3000/api"

def get_cell_status():
    response = requests.get(f"{API_BASE}/status")
    return response.json()

def add_peer(name, ip, public_key):
    data = {
        "name": name,
        "ip": ip,
        "public_key": public_key
    }
    response = requests.post(f"{API_BASE}/peers", json=data)
    return response.json()

def get_service_logs(service, lines=50):
    response = requests.get(f"{API_BASE}/logs?lines={lines}")
    return response.json()

# Usage
status = get_cell_status()
print(f"Cell status: {status['cell_name']}")

result = add_peer("alice", "10.0.0.2", "abc123...")
print(f"Add peer result: {result}")
```

### cURL Examples

```bash
# Get cell status
curl -X GET http://localhost:3000/api/status

# Add a peer
curl -X POST http://localhost:3000/api/peers \
  -H "Content-Type: application/json" \
  -d '{"name": "alice", "ip": "10.0.0.2", "public_key": "abc123..."}'

# Get service logs
curl -X GET "http://localhost:3000/api/logs?lines=100"

# Update configuration
curl -X PUT http://localhost:3000/api/config \
  -H "Content-Type: application/json" \
  -d '{"cell_name": "my-cell"}'
```

### JavaScript Client Example

```javascript
const API_BASE = 'http://localhost:3000/api';

async function getCellStatus() {
    const response = await fetch(`${API_BASE}/status`);
    return await response.json();
}

async function addPeer(name, ip, publicKey) {
    const response = await fetch(`${API_BASE}/peers`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            name: name,
            ip: ip,
            public_key: publicKey
        })
    });
    return await response.json();
}

// Usage
getCellStatus().then(status => {
    console.log('Cell status:', status);
});

addPeer('alice', '10.0.0.2', 'abc123...').then(result => {
    console.log('Add peer result:', result);
});
```

## Rate Limiting

Currently, no rate limiting is implemented. However, it's recommended to:

- Limit requests to reasonable frequencies
- Implement exponential backoff for retries
- Cache responses when appropriate

## Best Practices

1. **Error Handling**: Always check for errors in responses
2. **Logging**: Use appropriate log levels for debugging
3. **Configuration**: Validate configuration before applying
4. **Security**: Keep private keys and secrets secure
5. **Monitoring**: Regularly check service health
6. **Backup**: Create regular configuration backups

## Troubleshooting

### Common Issues

1. **Connection Refused**: Ensure the API server is running
2. **403 Forbidden**: Check that you're accessing from localhost
3. **Service Not Found**: Verify the service is properly configured
4. **Configuration Errors**: Check configuration validation

### Debug Commands

```bash
# Check API server status
curl -X GET http://localhost:3000/api/health

# Check all services status
curl -X GET http://localhost:3000/api/services/status

# Get recent logs
curl -X GET "http://localhost:3000/api/logs?lines=50"

# Check health history
curl -X GET http://localhost:3000/api/health/history
```

## Version History

- **v1.0.0**: Initial API release with basic functionality
- **v1.1.0**: Added configuration management and backup features
- **v1.2.0**: Enhanced logging and monitoring capabilities
- **v1.3.0**: Added service bus and event-driven architecture
- **v1.4.0**: Improved error handling and validation

## Support

For issues and questions:

1. Check the logs: `GET /api/logs`
2. Verify service status: `GET /api/services/status`
3. Review configuration: `GET /api/config`
4. Check health history: `GET /api/health/history`

## License

This API is part of the Personal Internet Cell project and is licensed under the MIT License.