diff --git a/docs/CORE_API_SPEC.md b/docs/CORE_API_SPEC.md deleted file mode 100644 index 8f76dc7..0000000 --- a/docs/CORE_API_SPEC.md +++ /dev/null @@ -1,346 +0,0 @@ -# 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" -} -```