jesus/prvng_platform

Fork 0

Jesús Pérez f2be2414e4 core: init repo and codebase

2025-10-07 10:59:52 +01:00

13 KiB

Raw Permalink Blame History

Extension Registry API Documentation

Version: 1.0.0 Base URL: http://localhost:8082/api/v1

Authentication
Extension Endpoints
System Endpoints
Error Responses
Data Models

Authentication

The Extension Registry API does not require authentication for read operations. Backend authentication (Gitea/OCI) is handled server-side via configuration.

Extension Endpoints

List Extensions

Retrieve a list of available extensions with optional filtering and pagination.

Endpoint: GET /extensions

Query Parameters:

Parameter	Type	Required	Description
`type`	string	No	Filter by extension type: `provider`, `taskserv`, `cluster`
`source`	string	No	Filter by source: `gitea`, `oci`
`limit`	integer	No	Maximum results (default: 100, max: 1000)
`offset`	integer	No	Pagination offset (default: 0)

Example Request:

curl "http://localhost:8082/api/v1/extensions?type=provider&limit=10"

Example Response (200 OK):

[
  {
    "name": "aws",
    "type": "provider",
    "version": "1.2.0",
    "description": "AWS provider for provisioning infrastructure",
    "author": "provisioning-team",
    "repository": "https://gitea.example.com/org/aws_prov",
    "source": "gitea",
    "published_at": "2025-10-06T12:00:00Z",
    "download_url": "https://gitea.example.com/org/aws_prov/releases/download/1.2.0/aws_prov.tar.gz",
    "checksum": "sha256:abc123...",
    "size": 1024000,
    "tags": ["cloud", "aws", "infrastructure"]
  },
  {
    "name": "upcloud",
    "type": "provider",
    "version": "2.1.3",
    "description": "UpCloud provider for European cloud infrastructure",
    "author": "provisioning-team",
    "repository": "https://gitea.example.com/org/upcloud_prov",
    "source": "gitea",
    "published_at": "2025-10-05T10:30:00Z",
    "download_url": "https://gitea.example.com/org/upcloud_prov/releases/download/2.1.3/upcloud_prov.tar.gz",
    "size": 890000
  }
]

Get Extension Metadata

Retrieve detailed metadata for a specific extension.

Endpoint: GET /extensions/{type}/{name}

Path Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	Extension type: `provider`, `taskserv`, `cluster`
`name`	string	Yes	Extension name

Example Request:

curl "http://localhost:8082/api/v1/extensions/provider/aws"

Example Response (200 OK):

{
  "name": "aws",
  "type": "provider",
  "version": "1.2.0",
  "description": "AWS provider for provisioning infrastructure",
  "author": "provisioning-team",
  "repository": "https://gitea.example.com/org/aws_prov",
  "source": "gitea",
  "published_at": "2025-10-06T12:00:00Z",
  "download_url": "https://gitea.example.com/org/aws_prov/releases/download/1.2.0/aws_prov.tar.gz",
  "checksum": "sha256:abc123...",
  "size": 1024000,
  "tags": ["cloud", "aws", "infrastructure"]
}

Error Response (404 Not Found):

{
  "error": "not_found",
  "message": "Extension provider/nonexistent not found"
}

List Extension Versions

Get all available versions for a specific extension.

Endpoint: GET /extensions/{type}/{name}/versions

Path Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	Extension type: `provider`, `taskserv`, `cluster`
`name`	string	Yes	Extension name

Example Request:

curl "http://localhost:8082/api/v1/extensions/taskserv/kubernetes/versions"

Example Response (200 OK):

[
  {
    "version": "1.28.0",
    "published_at": "2025-10-06T12:00:00Z",
    "download_url": "https://gitea.example.com/org/kubernetes_taskserv/releases/download/1.28.0/kubernetes_taskserv.tar.gz",
    "checksum": "sha256:def456...",
    "size": 2048000
  },
  {
    "version": "1.27.5",
    "published_at": "2025-09-15T10:30:00Z",
    "download_url": "https://gitea.example.com/org/kubernetes_taskserv/releases/download/1.27.5/kubernetes_taskserv.tar.gz",
    "checksum": "sha256:ghi789...",
    "size": 1980000
  },
  {
    "version": "1.27.4",
    "published_at": "2025-08-20T08:15:00Z",
    "download_url": "https://gitea.example.com/org/kubernetes_taskserv/releases/download/1.27.4/kubernetes_taskserv.tar.gz",
    "size": 1950000
  }
]

Download Extension

Download a specific version of an extension.

Endpoint: GET /extensions/{type}/{name}/{version}

Path Parameters:

Parameter	Type	Required	Description
`type`	string	Yes	Extension type: `provider`, `taskserv`, `cluster`
`name`	string	Yes	Extension name
`version`	string	Yes	Extension version (e.g., `1.2.0`)

Example Request:

curl -OJ "http://localhost:8082/api/v1/extensions/provider/aws/1.2.0"

Response:

Content-Type: application/octet-stream
Body: Binary data (tarball or archive)

Error Response (404 Not Found):

{
  "error": "not_found",
  "message": "Extension provider/aws version 1.2.0 not found"
}

Search Extensions

Search for extensions by name or description.

Endpoint: GET /extensions/search

Query Parameters:

Parameter	Type	Required	Description
`q`	string	Yes	Search query (case-insensitive)
`type`	string	No	Filter by extension type
`limit`	integer	No	Maximum results (default: 50, max: 100)

Example Request:

curl "http://localhost:8082/api/v1/extensions/search?q=kubernetes&type=taskserv&limit=5"

Example Response (200 OK):

[
  {
    "name": "kubernetes",
    "type": "taskserv",
    "version": "1.28.0",
    "description": "Kubernetes container orchestration platform",
    "author": "provisioning-team",
    "source": "gitea",
    "published_at": "2025-10-06T12:00:00Z"
  },
  {
    "name": "k3s",
    "type": "taskserv",
    "version": "1.27.5",
    "description": "Lightweight Kubernetes distribution",
    "author": "community",
    "source": "oci",
    "published_at": "2025-09-20T14:30:00Z"
  }
]

System Endpoints

Health Check

Check service health and backend status.

Endpoint: GET /health

Example Request:

curl "http://localhost:8082/api/v1/health"

Example Response (200 OK):

{
  "status": "healthy",
  "version": "0.1.0",
  "uptime": 3600,
  "backends": {
    "gitea": {
      "enabled": true,
      "healthy": true
    },
    "oci": {
      "enabled": true,
      "healthy": true,
      "error": null
    }
  }
}

Degraded Status (200 OK):

{
  "status": "degraded",
  "version": "0.1.0",
  "uptime": 7200,
  "backends": {
    "gitea": {
      "enabled": true,
      "healthy": false,
      "error": "Connection timeout"
    },
    "oci": {
      "enabled": true,
      "healthy": true
    }
  }
}

Metrics

Get Prometheus-formatted metrics.

Endpoint: GET /metrics

Example Request:

curl "http://localhost:8082/api/v1/metrics"

Example Response (200 OK):

# HELP http_requests_total Total HTTP requests
# TYPE http_requests_total counter
http_requests_total 1234

# HELP http_request_duration_seconds HTTP request duration
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{le="0.005"} 100
http_request_duration_seconds_bucket{le="0.01"} 200
http_request_duration_seconds_bucket{le="0.025"} 300
http_request_duration_seconds_sum 50.5
http_request_duration_seconds_count 1234

# HELP cache_hits_total Total cache hits
# TYPE cache_hits_total counter
cache_hits_total 987

# HELP cache_misses_total Total cache misses
# TYPE cache_misses_total counter
cache_misses_total 247

# HELP extensions_total Total extensions
# TYPE extensions_total gauge
extensions_total 45

Cache Statistics

Get cache performance statistics.

Endpoint: GET /cache/stats

Example Request:

curl "http://localhost:8082/api/v1/cache/stats"

Example Response (200 OK):

{
  "list_entries": 45,
  "metadata_entries": 120,
  "version_entries": 80,
  "total_entries": 245
}

Error Responses

All error responses follow this format:

{
  "error": "error_type",
  "message": "Human-readable error message",
  "details": "Optional additional details"
}

HTTP Status Codes

Status	Description
200 OK	Request successful
400 Bad Request	Invalid input (e.g., invalid extension type)
401 Unauthorized	Authentication failed
404 Not Found	Resource not found
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server error
503 Service Unavailable	Service temporarily unavailable

Error Types

Error Type	HTTP Status	Description
`not_found`	404	Extension or resource not found
`invalid_type`	400	Invalid extension type provided
`invalid_version`	400	Invalid version format
`auth_error`	401	Authentication failed
`rate_limit`	429	Too many requests
`config_error`	500	Server configuration error
`internal_error`	500	Internal server error

Data Models

Extension

interface Extension {
  name: string;              // Extension name
  type: ExtensionType;       // Extension type
  version: string;           // Current version (semver)
  description: string;       // Description
  author?: string;           // Author/organization
  repository?: string;       // Source repository URL
  source: ExtensionSource;   // Backend source
  published_at: string;      // ISO 8601 timestamp
  download_url?: string;     // Download URL
  checksum?: string;         // Checksum (e.g., sha256:...)
  size?: number;             // Size in bytes
  tags?: string[];           // Tags
}

ExtensionType

type ExtensionType = "provider" | "taskserv" | "cluster";

ExtensionSource

type ExtensionSource = "gitea" | "oci";

ExtensionVersion

interface ExtensionVersion {
  version: string;           // Version string (semver)
  published_at: string;      // ISO 8601 timestamp
  download_url?: string;     // Download URL
  checksum?: string;         // Checksum
  size?: number;             // Size in bytes
}

HealthResponse

interface HealthResponse {
  status: string;            // "healthy" | "degraded"
  version: string;           // Service version
  uptime: number;            // Uptime in seconds
  backends: BackendHealth;   // Backend health status
}

BackendHealth

interface BackendHealth {
  gitea: BackendStatus;
  oci: BackendStatus;
}

BackendStatus

interface BackendStatus {
  enabled: boolean;          // Backend enabled
  healthy: boolean;          // Backend healthy
  error?: string;            // Error message if unhealthy
}

Rate Limiting

Currently, the API does not enforce rate limiting. This may be added in future versions.

For high-volume usage, consider:

Implementing client-side rate limiting
Using the cache effectively
Batching requests when possible

Caching Behavior

The service implements LRU caching with TTL:

Cache TTL: Configurable (default: 5 minutes)
Cache Capacity: Configurable (default: 1000 entries)
Cache Keys:
- List: list:{type}:{source}
- Metadata: {type}/{name}
- Versions: {type}/{name}/versions

Cache headers are not currently exposed. Future versions may include:

X-Cache-Hit: true/false
X-Cache-TTL: {seconds}

Versioning

API version is specified in the URL path: /api/v1/

Major version changes will be introduced in new paths (e.g., /api/v2/).

Examples

Complete Workflow

# 1. Search for Kubernetes extensions
curl "http://localhost:8082/api/v1/extensions/search?q=kubernetes"

# 2. Get extension metadata
curl "http://localhost:8082/api/v1/extensions/taskserv/kubernetes"

# 3. List available versions
curl "http://localhost:8082/api/v1/extensions/taskserv/kubernetes/versions"

# 4. Download specific version
curl -OJ "http://localhost:8082/api/v1/extensions/taskserv/kubernetes/1.28.0"

# 5. Verify checksum (if provided)
sha256sum kubernetes_taskserv.tar.gz

Pagination

# Get first page
curl "http://localhost:8082/api/v1/extensions?limit=10&offset=0"

# Get second page
curl "http://localhost:8082/api/v1/extensions?limit=10&offset=10"

# Get third page
curl "http://localhost:8082/api/v1/extensions?limit=10&offset=20"

Filtering

# Only providers from Gitea
curl "http://localhost:8082/api/v1/extensions?type=provider&source=gitea"

# Only taskservs from OCI
curl "http://localhost:8082/api/v1/extensions?type=taskserv&source=oci"

# All clusters
curl "http://localhost:8082/api/v1/extensions?type=cluster"

Support

For issues and questions, see the main README or project documentation.

13 KiB Raw Permalink Blame History

Extension Registry API Documentation

Table of Contents

Authentication

Extension Endpoints

List Extensions

Get Extension Metadata

List Extension Versions

Download Extension

Search Extensions

System Endpoints

Health Check

Metrics

Cache Statistics

Error Responses

HTTP Status Codes

Error Types

Data Models

Extension

ExtensionType

ExtensionSource

ExtensionVersion

HealthResponse

BackendHealth

BackendStatus

Rate Limiting

Caching Behavior

Versioning

Examples

Complete Workflow

Pagination

Filtering

Support

13 KiB

Raw Permalink Blame History