tatlock-ui/docs/CORE_API_SPEC.md

# Core API Specification

Expected API endpoints for the Tatlock UI Control Room feature.

**Base URL:** `http://{host}:8083` (configurable via `CORE_API_URL`)

---

## Containers

### List Containers

```
GET /infrastructure/containers
```

**Query Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `all` | boolean | `true` | Include stopped containers |

**Response:** `200 OK`
```json
[
  {
    "Id": "abc123def456...",
    "Names": ["/container-name"],
    "Image": "nginx:latest",
    "State": "running",
    "Status": "Up 2 hours",
    "Labels": {
      "com.docker.compose.project": "my-stack",
      "com.docker.compose.service": "web"
    },
    "Ports": [
      {
        "IP": "0.0.0.0",
        "PrivatePort": 80,
        "PublicPort": 8080,
        "Type": "tcp"
      }
    ],
    "Mounts": [
      {
        "Type": "bind",
        "Source": "/host/path",
        "Destination": "/container/path",
        "Mode": "rw",
        "RW": true
      }
    ],
    "NetworkSettings": {
      "Networks": {
        "bridge": {}
      }
    },
    "Created": 1704067200,
    "SizeRw": 12345,
    "SizeRootFs": 67890
  }
]
```

---

### Get Container

```
GET /infrastructure/containers/{id}
```

**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Full container ID |

**Response:** `200 OK`
```json
{
  "Id": "abc123def456...",
  "Names": ["/container-name"],
  "Image": "nginx:latest",
  "State": "running",
  "Status": "Up 2 hours",
  "Labels": {},
  "Ports": [],
  "Mounts": [],
  "NetworkSettings": {},
  "Created": 1704067200
}
```

---

### Container Actions

```
POST /infrastructure/containers/{id}/{action}
```

**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Full container ID |
| `action` | string | One of: `start`, `stop`, `restart` |

**Response:** `204 No Content`

---

### Get Container Logs

```
GET /infrastructure/containers/{id}/logs
```

**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Full container ID |

**Query Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `tail` | integer | (all) | Number of lines from end |
| `timestamps` | boolean | `false` | Include timestamps |

**Response:** `200 OK`
```
Content-Type: text/plain

2024-01-01T12:00:00Z Log line 1
2024-01-01T12:00:01Z Log line 2
...
```

---

### Delete Container

```
DELETE /infrastructure/containers/{id}
```

**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Full container ID |

**Query Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `force` | boolean | `false` | Force remove running container |

**Response:** `204 No Content`

---

## Stacks

Stacks are Docker Compose projects. The stack ID is the value of the `com.docker.compose.project` label on containers.

### Get Stack Compose YAML

```
GET /infrastructure/stacks/{stackId}/compose
```

**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `stackId` | string | Stack name (compose project name) |

**Response:** `200 OK`
```
Content-Type: text/yaml

version: '3.8'
services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
  db:
    image: postgres:14
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
```

---

### Update Stack Compose YAML

```
PUT /infrastructure/stacks/{stackId}/compose
```

**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `stackId` | string | Stack name (compose project name) |

**Request Body:**
```
Content-Type: text/yaml

version: '3.8'
services:
  web:
    image: nginx:latest
    ...
```

**Response:** `204 No Content`

---

### Get Stack Environment Variables

```
GET /infrastructure/stacks/{stackId}/env
```

**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `stackId` | string | Stack name (compose project name) |

**Response:** `200 OK`
```json
{
  "DB_PASSWORD": "secret123",
  "API_KEY": "abc-def-ghi",
  "DEBUG": "false"
}
```

---

### Update Stack Environment Variables

```
PUT /infrastructure/stacks/{stackId}/env
```

**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `stackId` | string | Stack name (compose project name) |

**Request Body:**
```json
{
  "DB_PASSWORD": "new-secret",
  "API_KEY": "new-key",
  "DEBUG": "true"
}
```

**Response:** `204 No Content`

---

### Deploy Stack

Redeploys the stack with current YAML and environment variables.

```
POST /infrastructure/stacks/{stackId}/deploy
```

**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `stackId` | string | Stack name (compose project name) |

**Response:** `202 Accepted`

---

### Rebuild Stack

Pulls fresh images and recreates all containers in the stack.

```
POST /infrastructure/stacks/{stackId}/rebuild
```

**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `stackId` | string | Stack name (compose project name) |

**Response:** `202 Accepted`

---

## Data Types Reference

### Container States

| Value | Description |
|-------|-------------|
| `created` | Container created but not started |
| `running` | Container is running |
| `paused` | Container is paused |
| `restarting` | Container is restarting |
| `removing` | Container is being removed |
| `exited` | Container has exited |
| `dead` | Container is dead |

### Port Types

| Value | Description |
|-------|-------------|
| `tcp` | TCP port |
| `udp` | UDP port |

### Mount Types

| Value | Description |
|-------|-------------|
| `bind` | Bind mount from host |
| `volume` | Docker volume |
| `tmpfs` | Temporary filesystem |

---

## Error Responses

All endpoints return standard HTTP error codes:

| Code | Description |
|------|-------------|
| `400` | Bad Request - Invalid parameters |
| `404` | Not Found - Container/Stack not found |
| `409` | Conflict - Container already in requested state |
| `500` | Internal Server Error |

**Error Body:**
```json
{
  "error": "Container not found",
  "code": "NOT_FOUND"
}
```