// RESTFUL API

Complete Programmatic Control

Two API versions (v1.0 for operations, v2.0 for introspection) enable full programmatic control of your distributed cluster.

Real-World Use Case: GitOps Automation

Deploy applications to your cluster via Git commits. Webhooks trigger orchestrations that manage infrastructure as code.

1. Complete CRUD Operations

API v1.0 - Full Operations
# Create orchestration
$ curl -X POST https://node:20194/api/v1.0/orchestrations \
  -H "Authorization: Bearer $JWT" \
  -d '{
  "name": "deploy-app",
  "version": 1,
  "steps": [...]
}'

# Launch execution
$ curl -X POST https://node:20194/api/v1.0/launch \
  -d '{
  "orchestration_id": "deploy-app",
  "targets": ["prod-servers"]
}'

# Query results
$ curl https://node:20194/api/v1.0/executions \
  -H "Authorization: Bearer $JWT"

# Manage vault
$ curl -X POST https://node:20194/api/v1.0/vault \
  -d '{"name": "api_key", "value": "secret"}'

API v1.0 Resources

  • Orchestrations - Define and manage workflows
  • Executions - Monitor running operations
  • Vault - Manage secrets programmatically
  • Users & Groups - Access control
  • Servers - Register and query infrastructure
  • Files - Distribute files across cluster

2. Data Dictionary (API v2.0)

Introspection & Discovery

API v2.0 lets clients discover available resources, their fields, relationships, and validation rules without documentation.

  • List all available resources
  • Discover field types and constraints
  • Explore relationships between entities
  • Validate payloads before submission
API v2.0 - Data Dictionary
# Get resource schema
$ curl https://node:20194/api/v2/data-dictionary/orchestrations

{
  "name": {
    "type": "string",
    "required": true,
    "maxLength": 100
  },
  "version": {
    "type": "integer",
    "minimum": 1
  },
  "steps": {
    "type": "array",
    "items": {...}
  }
}

3. GitOps Webhook Integration

GitHub Webhook Handler
#!/bin/bash
# Webhook endpoint receives push event

curl -X POST https://dimensigon:20194/api/v1.0/launch \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
  "orchestration_id": "deploy-from-git",
  "params": {
    "repo": "'"$GITHUB_REPOSITORY"'",
    "branch": "'"$GITHUB_REF"'",
    "commit": "'"$GITHUB_SHA"'"
  }
}'

Declarative Infrastructure

  • Git push triggers deployment automatically
  • API handles infrastructure changes
  • Full audit trail of all changes
  • Easy rollback via git revert + webhook

Additional Capabilities

🎯 Real-Time Event Streaming

Subscribe to orchestration events in real-time via WebSocket. Get live progress, status, and error notifications.

WebSocket Stream
ws://dimensigon/api/v1/stream
"event": "orchestration.step_start",
"timestamp": "2025-03-12T14:32Z",
"step_id": "validate-db",
"progress": 42%

📊 Batch Operation API

Execute multiple orchestrations in a single API call with dependency ordering and parallel execution.

Batch Execution
"batch": [
  { "id": "init",
    "orch": "setup" },
  { "id": "deploy",
    "after": ["init"] }
]

🔄 GraphQL Schema Support

In addition to REST, query orchestrations using GraphQL for flexible, efficient data fetching.

GraphQL Query
query {
  orchestrations(filter: {status: "running"}) {
    id, status, progress,
    steps { name, duration }
  }
}

⚡ Rate Limiting & Quotas

Built-in rate limiting and quota management per API key with graceful degradation.

Rate Limits
"rate_limits": {
  "requests/sec": 100,
  "burst": 500,
  "quota": "10k/day"
}
🔌

Universal Integration

Any language or tool can interact with Dimensigon via standard HTTP.

📚

Self-Documenting

API v2.0 data dictionary eliminates the need for manual API docs.

⚙️

Programmatic Control

Build custom dashboards, CLIs, and automation on top of the API.

🔐

JWT Authentication

Stateless, scalable auth with fine-grained permissions.

Start Building Back to Features