jesus/prvng_platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
prvng_platform/provisioning-server/API_REFERENCE.md
Jesús Pérez f2be2414e4 core: init repo and codebase
2025-10-07 10:59:52 +01:00

9.1 KiB
Raw Blame History

Provisioning API Reference

Complete API reference for the Provisioning API Server.

Base URL

http://localhost:8083

Authentication

All protected endpoints require JWT authentication via the Authorization header:

Authorization: Bearer <token>

Response Format

Success Response

{
  "id": "string",
  "status": "pending|running|completed|failed|cancelled",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:00:00Z",
  "result": {},
  "error": null
}

Error Response

{
  "error": "ERROR_CODE",
  "message": "Human readable error message",
  "code": "400"
}

Endpoints

Authentication

POST /v1/auth/login

Login and receive access token.

Request:

{
  "username": "admin",
  "password": "admin123"
}

Response:

{
  "token": "eyJhbGc...",
  "refresh_token": "eyJhbGc...",
  "expires_in": 86400
}

Status Codes:

  • 200 - Success
  • 401 - Invalid credentials

POST /v1/auth/refresh

Refresh access token using refresh token.

Request:

{
  "refresh_token": "eyJhbGc..."
}

Response:

{
  "token": "eyJhbGc...",
  "refresh_token": "eyJhbGc...",
  "expires_in": 86400
}

Status Codes:

  • 200 - Success
  • 401 - Invalid refresh token

Servers

GET /v1/servers

List all servers.

Headers:

  • Authorization: Bearer <token>

Response:

[
  {
    "id": "srv-abc123",
    "hostname": "web-01",
    "provider": "upcloud",
    "plan": "2xCPU-4GB",
    "zone": "de-fra1",
    "ip_address": "10.0.0.1",
    "status": "running",
    "created_at": "2025-10-06T12:00:00Z"
  }
]

Required Permission: server_read

Status Codes:

  • 200 - Success
  • 401 - Unauthorized
  • 403 - Forbidden

POST /v1/servers/create

Create a new server.

Headers:

  • Authorization: Bearer <token>

Request:

{
  "workspace": "production",
  "provider": "upcloud",
  "plan": "2xCPU-4GB",
  "hostname": "web-01",
  "zone": "de-fra1",
  "check_mode": false,
  "tags": ["web", "production"]
}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:00:00Z",
  "result": null,
  "error": null
}

Required Permission: server_create

Status Codes:

  • 200 - Success
  • 400 - Bad request (validation error)
  • 401 - Unauthorized
  • 403 - Forbidden

DELETE /v1/servers/{id}

Delete a server.

Headers:

  • Authorization: Bearer <token>

Request:

{
  "workspace": "production",
  "server_id": "srv-abc123",
  "force": false
}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:00:00Z",
  "result": null,
  "error": null
}

Required Permission: server_delete

Status Codes:

  • 200 - Success
  • 404 - Server not found
  • 401 - Unauthorized
  • 403 - Forbidden

GET /v1/servers/{id}/status

Get server status.

Headers:

  • Authorization: Bearer <token>

Response:

{
  "id": "srv-abc123",
  "hostname": "web-01",
  "provider": "upcloud",
  "plan": "2xCPU-4GB",
  "zone": "de-fra1",
  "ip_address": "10.0.0.1",
  "status": "running",
  "created_at": "2025-10-06T12:00:00Z"
}

Required Permission: server_read

Status Codes:

  • 200 - Success
  • 404 - Server not found
  • 401 - Unauthorized
  • 403 - Forbidden

Taskservs

GET /v1/taskservs

List all taskservs.

Headers:

  • Authorization: Bearer <token>

Response:

[
  {
    "id": "tsk-xyz789",
    "name": "kubernetes",
    "version": "1.28.0",
    "servers": ["web-01", "web-02"],
    "status": "running",
    "created_at": "2025-10-06T12:00:00Z"
  }
]

Required Permission: taskserv_read

POST /v1/taskservs/create

Create a new taskserv.

Headers:

  • Authorization: Bearer <token>

Request:

{
  "workspace": "production",
  "name": "kubernetes",
  "servers": ["web-01", "web-02"],
  "config": {
    "version": "1.28.0"
  },
  "check_mode": false
}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:00:00Z",
  "result": null,
  "error": null
}

Required Permission: taskserv_create

DELETE /v1/taskservs/{id}

Delete a taskserv.

Headers:

  • Authorization: Bearer <token>

Request:

{
  "workspace": "production",
  "taskserv_id": "tsk-xyz789"
}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:00:00Z",
  "result": null,
  "error": null
}

Required Permission: taskserv_delete

Workflows

POST /v1/workflows/submit

Submit a workflow.

Headers:

  • Authorization: Bearer <token>

Request:

{
  "workspace": "production",
  "workflow_type": "cluster_create",
  "parameters": {
    "cluster_name": "k8s-prod",
    "node_count": 3
  }
}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:00:00Z",
  "result": null,
  "error": null
}

Required Permission: workflow_submit

GET /v1/workflows/{id}

Get workflow details.

Headers:

  • Authorization: Bearer <token>

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "workflow_type": "cluster_create",
  "status": "running",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:05:00Z"
}

Required Permission: workflow_read

POST /v1/workflows/{id}/cancel

Cancel a workflow.

Headers:

  • Authorization: Bearer <token>

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "cancelled",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:10:00Z",
  "result": null,
  "error": null
}

Required Permission: workflow_cancel

Operations

GET /v1/operations

List all operations.

Headers:

  • Authorization: Bearer <token>

Response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "created_at": "2025-10-06T12:00:00Z",
    "updated_at": "2025-10-06T12:05:00Z",
    "result": {
      "server_id": "srv-abc123"
    },
    "error": null
  }
]

Required Permission: operation_read

GET /v1/operations/{id}

Get operation status.

Headers:

  • Authorization: Bearer <token>

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:05:00Z",
  "result": {
    "server_id": "srv-abc123",
    "ip_address": "10.0.0.1"
  },
  "error": null
}

Required Permission: operation_read

POST /v1/operations/{id}/cancel

Cancel an operation.

Headers:

  • Authorization: Bearer <token>

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "cancelled",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:10:00Z",
  "result": null,
  "error": null
}

Required Permission: operation_cancel

Workspaces

GET /v1/workspaces

List all workspaces.

Headers:

  • Authorization: Bearer <token>

Response:

[
  {
    "name": "production",
    "path": "/opt/workspaces/production",
    "active": true,
    "last_used": "2025-10-06T12:00:00Z"
  }
]

Required Permission: workspace_read

POST /v1/workspaces/create

Create a workspace.

Headers:

  • Authorization: Bearer <token>

Request:

{
  "name": "staging",
  "path": "/opt/workspaces/staging",
  "activate": false
}

Response:

{
  "name": "staging",
  "path": "/opt/workspaces/staging",
  "active": false,
  "last_used": null
}

Required Permission: workspace_create

System

GET /health

Health check endpoint (no authentication required).

Response:

{
  "status": "healthy",
  "version": "0.1.0",
  "uptime_seconds": 3600
}

Status Codes:

  • 200 - Server is healthy

GET /v1/metrics

Get server metrics.

Headers:

  • Authorization: Bearer <token>

Response:

{
  "uptime_seconds": 3600,
  "tasks": {
    "total": 42,
    "running": 3
  }
}

Required Permission: system_metrics

Status Codes

  • 200 - OK
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 409 - Conflict
  • 500 - Internal Server Error
  • 503 - Service Unavailable

Rate Limiting

Currently not implemented. Future versions may include:

  • Per-user rate limits
  • IP-based rate limits
  • Operation-specific limits

Pagination

Currently not implemented. All list endpoints return complete results.

Future versions may include:

  • ?page=1&per_page=20
  • Link headers for pagination
  • Total count in response

Filtering

Currently not implemented. Future versions may include:

  • ?status=running
  • ?workspace=production
  • ?created_after=2025-10-01