# Extension Registry API Documentation\n\nVersion: 1.0.0\nBase URL: `http://localhost:8082/api/v1`\n\n## Table of Contents\n\n- [Authentication](#authentication)\n- [Extension Endpoints](#extension-endpoints)\n- [System Endpoints](#system-endpoints)\n- [Error Responses](#error-responses)\n- [Data Models](#data-models)\n\n## Authentication\n\nThe Extension Registry API does not require authentication for read operations. Backend authentication (Gitea/OCI) is handled server-side via \nconfiguration.\n\n## Extension Endpoints\n\n### List Extensions\n\nRetrieve a list of available extensions with optional filtering and pagination.\n\n**Endpoint**: `GET /extensions`\n\n**Query Parameters**:\n\n| Parameter | Type | Required | Description |\n| ----------- | ------ | ---------- | ------------- |\n| `type` | string | No | Filter by extension type: `provider`, `taskserv`, `cluster` |\n| `source` | string | No | Filter by source: `gitea`, `oci` |\n| `limit` | integer | No | Maximum results (default: 100, max: 1000) |\n| `offset` | integer | No | Pagination offset (default: 0) |\n\n**Example Request**:\n\n```{$detected_lang}\ncurl "http://localhost:8082/api/v1/extensions?type=provider&limit=10"\n```\n\n**Example Response** (200 OK):\n\n```{$detected_lang}\n[\n  {\n    "name": "aws",\n    "type": "provider",\n    "version": "1.2.0",\n    "description": "AWS provider for provisioning infrastructure",\n    "author": "provisioning-team",\n    "repository": "https://gitea.example.com/org/aws_prov",\n    "source": "gitea",\n    "published_at": "2025-10-06T12:00:00Z",\n    "download_url": "https://gitea.example.com/org/aws_prov/releases/download/1.2.0/aws_prov.tar.gz",\n    "checksum": "sha256:abc123...",\n    "size": 1024000,\n    "tags": ["cloud", "aws", "infrastructure"]\n  },\n  {\n    "name": "upcloud",\n    "type": "provider",\n    "version": "2.1.3",\n    "description": "UpCloud provider for European cloud infrastructure",\n    "author": "provisioning-team",\n    "repository": "https://gitea.example.com/org/upcloud_prov",\n    "source": "gitea",\n    "published_at": "2025-10-05T10:30:00Z",\n    "download_url": "https://gitea.example.com/org/upcloud_prov/releases/download/2.1.3/upcloud_prov.tar.gz",\n    "size": 890000\n  }\n]\n```\n\n---\n\n### Get Extension Metadata\n\nRetrieve detailed metadata for a specific extension.\n\n**Endpoint**: `GET /extensions/{type}/{name}`\n\n**Path Parameters**:\n\n| Parameter | Type | Required | Description |\n| ----------- | ------ | ---------- | ------------- |\n| `type` | string | Yes | Extension type: `provider`, `taskserv`, `cluster` |\n| `name` | string | Yes | Extension name |\n\n**Example Request**:\n\n```{$detected_lang}\ncurl "http://localhost:8082/api/v1/extensions/provider/aws"\n```\n\n**Example Response** (200 OK):\n\n```{$detected_lang}\n{\n  "name": "aws",\n  "type": "provider",\n  "version": "1.2.0",\n  "description": "AWS provider for provisioning infrastructure",\n  "author": "provisioning-team",\n  "repository": "https://gitea.example.com/org/aws_prov",\n  "source": "gitea",\n  "published_at": "2025-10-06T12:00:00Z",\n  "download_url": "https://gitea.example.com/org/aws_prov/releases/download/1.2.0/aws_prov.tar.gz",\n  "checksum": "sha256:abc123...",\n  "size": 1024000,\n  "tags": ["cloud", "aws", "infrastructure"]\n}\n```\n\n**Error Response** (404 Not Found):\n\n```{$detected_lang}\n{\n  "error": "not_found",\n  "message": "Extension provider/nonexistent not found"\n}\n```\n\n---\n\n### List Extension Versions\n\nGet all available versions for a specific extension.\n\n**Endpoint**: `GET /extensions/{type}/{name}/versions`\n\n**Path Parameters**:\n\n| Parameter | Type | Required | Description |\n| ----------- | ------ | ---------- | ------------- |\n| `type` | string | Yes | Extension type: `provider`, `taskserv`, `cluster` |\n| `name` | string | Yes | Extension name |\n\n**Example Request**:\n\n```{$detected_lang}\ncurl "http://localhost:8082/api/v1/extensions/taskserv/kubernetes/versions"\n```\n\n**Example Response** (200 OK):\n\n```{$detected_lang}\n[\n  {\n    "version": "1.28.0",\n    "published_at": "2025-10-06T12:00:00Z",\n    "download_url": "https://gitea.example.com/org/kubernetes_taskserv/releases/download/1.28.0/kubernetes_taskserv.tar.gz",\n    "checksum": "sha256:def456...",\n    "size": 2048000\n  },\n  {\n    "version": "1.27.5",\n    "published_at": "2025-09-15T10:30:00Z",\n    "download_url": "https://gitea.example.com/org/kubernetes_taskserv/releases/download/1.27.5/kubernetes_taskserv.tar.gz",\n    "checksum": "sha256:ghi789...",\n    "size": 1980000\n  },\n  {\n    "version": "1.27.4",\n    "published_at": "2025-08-20T08:15:00Z",\n    "download_url": "https://gitea.example.com/org/kubernetes_taskserv/releases/download/1.27.4/kubernetes_taskserv.tar.gz",\n    "size": 1950000\n  }\n]\n```\n\n---\n\n### Download Extension\n\nDownload a specific version of an extension.\n\n**Endpoint**: `GET /extensions/{type}/{name}/{version}`\n\n**Path Parameters**:\n\n| Parameter | Type | Required | Description |\n| ----------- | ------ | ---------- | ------------- |\n| `type` | string | Yes | Extension type: `provider`, `taskserv`, `cluster` |\n| `name` | string | Yes | Extension name |\n| `version` | string | Yes | Extension version (e.g., `1.2.0`) |\n\n**Example Request**:\n\n```{$detected_lang}\ncurl -OJ "http://localhost:8082/api/v1/extensions/provider/aws/1.2.0"\n```\n\n**Response**:\n\n- **Content-Type**: `application/octet-stream`\n- **Body**: Binary data (tarball or archive)\n\n**Error Response** (404 Not Found):\n\n```{$detected_lang}\n{\n  "error": "not_found",\n  "message": "Extension provider/aws version 1.2.0 not found"\n}\n```\n\n---\n\n### Search Extensions\n\nSearch for extensions by name or description.\n\n**Endpoint**: `GET /extensions/search`\n\n**Query Parameters**:\n\n| Parameter | Type | Required | Description |\n| ----------- | ------ | ---------- | ------------- |\n| `q` | string | Yes | Search query (case-insensitive) |\n| `type` | string | No | Filter by extension type |\n| `limit` | integer | No | Maximum results (default: 50, max: 100) |\n\n**Example Request**:\n\n```{$detected_lang}\ncurl "http://localhost:8082/api/v1/extensions/search?q=kubernetes&type=taskserv&limit=5"\n```\n\n**Example Response** (200 OK):\n\n```{$detected_lang}\n[\n  {\n    "name": "kubernetes",\n    "type": "taskserv",\n    "version": "1.28.0",\n    "description": "Kubernetes container orchestration platform",\n    "author": "provisioning-team",\n    "source": "gitea",\n    "published_at": "2025-10-06T12:00:00Z"\n  },\n  {\n    "name": "k3s",\n    "type": "taskserv",\n    "version": "1.27.5",\n    "description": "Lightweight Kubernetes distribution",\n    "author": "community",\n    "source": "oci",\n    "published_at": "2025-09-20T14:30:00Z"\n  }\n]\n```\n\n---\n\n## System Endpoints\n\n### Health Check\n\nCheck service health and backend status.\n\n**Endpoint**: `GET /health`\n\n**Example Request**:\n\n```{$detected_lang}\ncurl "http://localhost:8082/api/v1/health"\n```\n\n**Example Response** (200 OK):\n\n```{$detected_lang}\n{\n  "status": "healthy",\n  "version": "0.1.0",\n  "uptime": 3600,\n  "backends": {\n    "gitea": {\n      "enabled": true,\n      "healthy": true\n    },\n    "oci": {\n      "enabled": true,\n      "healthy": true,\n      "error": null\n    }\n  }\n}\n```\n\n**Degraded Status** (200 OK):\n\n```{$detected_lang}\n{\n  "status": "degraded",\n  "version": "0.1.0",\n  "uptime": 7200,\n  "backends": {\n    "gitea": {\n      "enabled": true,\n      "healthy": false,\n      "error": "Connection timeout"\n    },\n    "oci": {\n      "enabled": true,\n      "healthy": true\n    }\n  }\n}\n```\n\n---\n\n### Metrics\n\nGet Prometheus-formatted metrics.\n\n**Endpoint**: `GET /metrics`\n\n**Example Request**:\n\n```{$detected_lang}\ncurl "http://localhost:8082/api/v1/metrics"\n```\n\n**Example Response** (200 OK):\n\n```{$detected_lang}\n# HELP http_requests_total Total HTTP requests\n# TYPE http_requests_total counter\nhttp_requests_total 1234\n\n# HELP http_request_duration_seconds HTTP request duration\n# TYPE http_request_duration_seconds histogram\nhttp_request_duration_seconds_bucket{le="0.005"} 100\nhttp_request_duration_seconds_bucket{le="0.01"} 200\nhttp_request_duration_seconds_bucket{le="0.025"} 300\nhttp_request_duration_seconds_sum 50.5\nhttp_request_duration_seconds_count 1234\n\n# HELP cache_hits_total Total cache hits\n# TYPE cache_hits_total counter\ncache_hits_total 987\n\n# HELP cache_misses_total Total cache misses\n# TYPE cache_misses_total counter\ncache_misses_total 247\n\n# HELP extensions_total Total extensions\n# TYPE extensions_total gauge\nextensions_total 45\n```\n\n---\n\n### Cache Statistics\n\nGet cache performance statistics.\n\n**Endpoint**: `GET /cache/stats`\n\n**Example Request**:\n\n```{$detected_lang}\ncurl "http://localhost:8082/api/v1/cache/stats"\n```\n\n**Example Response** (200 OK):\n\n```{$detected_lang}\n{\n  "list_entries": 45,\n  "metadata_entries": 120,\n  "version_entries": 80,\n  "total_entries": 245\n}\n```\n\n---\n\n## Error Responses\n\nAll error responses follow this format:\n\n```{$detected_lang}\n{\n  "error": "error_type",\n  "message": "Human-readable error message",\n  "details": "Optional additional details"\n}\n```\n\n### HTTP Status Codes\n\n| Status | Description |\n| -------- | ------------- |\n| 200 OK | Request successful |\n| 400 Bad Request | Invalid input (e.g., invalid extension type) |\n| 401 Unauthorized | Authentication failed |\n| 404 Not Found | Resource not found |\n| 429 Too Many Requests | Rate limit exceeded |\n| 500 Internal Server Error | Server error |\n| 503 Service Unavailable | Service temporarily unavailable |\n\n### Error Types\n\n| Error Type | HTTP Status | Description |\n| ------------ | ------------- | ------------- |\n| `not_found` | 404 | Extension or resource not found |\n| `invalid_type` | 400 | Invalid extension type provided |\n| `invalid_version` | 400 | Invalid version format |\n| `auth_error` | 401 | Authentication failed |\n| `rate_limit` | 429 | Too many requests |\n| `config_error` | 500 | Server configuration error |\n| `internal_error` | 500 | Internal server error |\n\n---\n\n## Data Models\n\n### Extension\n\n```{$detected_lang}\ninterface Extension {\n  name: string;              // Extension name\n  type: ExtensionType;       // Extension type\n  version: string;           // Current version (semver)\n  description: string;       // Description\n  author?: string;           // Author/organization\n  repository?: string;       // Source repository URL\n  source: ExtensionSource;   // Backend source\n  published_at: string;      // ISO 8601 timestamp\n  download_url?: string;     // Download URL\n  checksum?: string;         // Checksum (e.g., sha256:...)\n  size?: number;             // Size in bytes\n  tags?: string[];           // Tags\n}\n```\n\n### ExtensionType\n\n```{$detected_lang}\ntype ExtensionType = "provider" | "taskserv" | "cluster";\n```\n\n### ExtensionSource\n\n```{$detected_lang}\ntype ExtensionSource = "gitea" | "oci";\n```\n\n### ExtensionVersion\n\n```{$detected_lang}\ninterface ExtensionVersion {\n  version: string;           // Version string (semver)\n  published_at: string;      // ISO 8601 timestamp\n  download_url?: string;     // Download URL\n  checksum?: string;         // Checksum\n  size?: number;             // Size in bytes\n}\n```\n\n### HealthResponse\n\n```{$detected_lang}\ninterface HealthResponse {\n  status: string;            // "healthy" | "degraded"\n  version: string;           // Service version\n  uptime: number;            // Uptime in seconds\n  backends: BackendHealth;   // Backend health status\n}\n```\n\n### BackendHealth\n\n```{$detected_lang}\ninterface BackendHealth {\n  gitea: BackendStatus;\n  oci: BackendStatus;\n}\n```\n\n### BackendStatus\n\n```{$detected_lang}\ninterface BackendStatus {\n  enabled: boolean;          // Backend enabled\n  healthy: boolean;          // Backend healthy\n  error?: string;            // Error message if unhealthy\n}\n```\n\n---\n\n## Rate Limiting\n\nCurrently, the API does not enforce rate limiting. This may be added in future versions.\n\nFor high-volume usage, consider:\n\n- Implementing client-side rate limiting\n- Using the cache effectively\n- Batching requests when possible\n\n---\n\n## Caching Behavior\n\nThe service implements LRU caching with TTL:\n\n- **Cache TTL**: Configurable (default: 5 minutes)\n- **Cache Capacity**: Configurable (default: 1000 entries)\n- **Cache Keys**:\n  - List: `list:{type}:{source}`\n  - Metadata: `{type}/{name}`\n  - Versions: `{type}/{name}/versions`\n\nCache headers are not currently exposed. Future versions may include:\n\n- `X-Cache-Hit: true/false`\n- `X-Cache-TTL: {seconds}`\n\n---\n\n## Versioning\n\nAPI version is specified in the URL path: `/api/v1/`\n\nMajor version changes will be introduced in new paths (e.g., `/api/v2/`).\n\n---\n\n## Examples\n\n### Complete Workflow\n\n```{$detected_lang}\n# 1. Search for Kubernetes extensions\ncurl "http://localhost:8082/api/v1/extensions/search?q=kubernetes"\n\n# 2. Get extension metadata\ncurl "http://localhost:8082/api/v1/extensions/taskserv/kubernetes"\n\n# 3. List available versions\ncurl "http://localhost:8082/api/v1/extensions/taskserv/kubernetes/versions"\n\n# 4. Download specific version\ncurl -OJ "http://localhost:8082/api/v1/extensions/taskserv/kubernetes/1.28.0"\n\n# 5. Verify checksum (if provided)\nsha256sum kubernetes_taskserv.tar.gz\n```\n\n### Pagination\n\n```{$detected_lang}\n# Get first page\ncurl "http://localhost:8082/api/v1/extensions?limit=10&offset=0"\n\n# Get second page\ncurl "http://localhost:8082/api/v1/extensions?limit=10&offset=10"\n\n# Get third page\ncurl "http://localhost:8082/api/v1/extensions?limit=10&offset=20"\n```\n\n### Filtering\n\n```{$detected_lang}\n# Only providers from Gitea\ncurl "http://localhost:8082/api/v1/extensions?type=provider&source=gitea"\n\n# Only taskservs from OCI\ncurl "http://localhost:8082/api/v1/extensions?type=taskserv&source=oci"\n\n# All clusters\ncurl "http://localhost:8082/api/v1/extensions?type=cluster"\n```\n\n---\n\n## Support\n\nFor issues and questions, see the main README or project documentation.