Engine API Architecture

This document details the architectural design, protocol boundaries, and structural concepts of the Niksphere Engine API.

1. Overview

The Niksphere Engine exposes a structured, multi-protocol interface designed to serve administrative tooling, application consumers, infrastructure monitoring, and interactive client frontends. The API architecture is organized into four distinct functional pillars: the System API (/api/v1/health) provides unauthenticated operational and health probes for infrastructure orchestrators and monitoring tools; the Admin API (/api/v1/admin/*) serves as the control and management plane for server administration, package deployments, user identities, and infrastructure monitoring via HTTP REST and WebSockets; the App API (/api/v1/{appId}/*) acts as the primary domain gateway for installed applications, providing remote execution of Pascal business logic as well as declarative data access in future releases; and the Client API (/api/v1/client) provides a dedicated, bidirectional WebSocket protocol designed for interactive user-facing frontends requiring real-time state synchronization.

Pillar	Base Route	Protocol	Core Responsibilities	Primary Consumers
System API	/api/v1/health	HTTP REST	• Service liveness & readiness probes • Database connectivity status • Infrastructure health monitoring	Load balancers, Kubernetes / Docker health checks, Uptime monitors, DevOps
Admin API	/api/v1/admin/*	HTTP REST & WebSocket	• Application package lifecycle (upload, publish, install, uninstall) • Local user identities & credentials • External OIDC IdP federation • Live log streaming (/monitor) & schema exploration	CLI, System Admins, CI/CD pipelines
App API	/api/v1/{appId}/*	HTTP REST	• Symbol execution (Pascal unit procedures/functions RPC) • Execution of Pascal business logic routines • Entity querying & CRUD data operations (Roadmap)	End-users, external integrations, background services
Client API	/api/v1/client	WebSocket	• Real-time UI state synchronization • Push events and notifications • Interactive session lifecycle & hot-reload broadcast	Niksphere Web UI, frontend client runtimes

2. System API (/api/v1/health)

The System API is a lightweight, unauthenticated HTTP interface intended for infrastructure orchestrators (such as Kubernetes liveness/readiness probes, Docker healthchecks, or cloud load balancers) and monitoring systems.

2.1 Health Check (GET /api/v1/health)

Inspects service operational status and tests active database connectivity via Ping().

• Route: GET /api/v1/health
• Authentication: None (Public / Unauthenticated)
• Response Status Codes:
  • 200 OK: Server process and underlying database connection are healthy.
  • 503 Service Unavailable: Server is running, but database connection has failed (status: "degraded").

Healthy Response Example (200 OK):

{
  "status": "ok",
  "service": "niksphere-engine",
  "database": "up",
  "timestamp": "2026-08-24T12:00:00Z"
}

Degraded Response Example (503 Service Unavailable):

{
  "status": "degraded",
  "service": "niksphere-engine",
  "database": "down",
  "timestamp": "2026-08-24T12:00:00Z"
}

3. Admin API (/api/v1/admin/*)

The Admin API serves as the central control and management plane of the Niksphere Engine. It is utilized primarily by platform administrators, CI/CD deployment automation, and developer tooling (such as the Niksphere CLI via nik env and nik dev).

Operationally, the Admin API encompasses three principal functional domains:

• Application Lifecycle Management: Governs the end-to-end lifecycle of compiled application packages (.nikapp). This includes atomic package publishing (POST /api/v1/admin/apps/publish), manual multi-version deployments, version installations and uninstallations, package binary downloads, and complete database teardowns (POST /api/v1/admin/apps/{id}/drop-data).
• Identity & Security Federation: Configures and oversees the platform's security subsystem. It handles local administrative user accounts and credentials (/api/v1/admin/identities), alongside federated enterprise OpenID Connect (OIDC) identity provider registrations (/api/v1/admin/idps/external) such as Microsoft Entra ID, Keycloak, or Okta.
• Data Inspection & Live Telemetry: Equips developer tooling with low-level schema inspection endpoints (/api/v1/admin/data/*) to explore physical database tables, as well as persistent WebSocket channels (GET /api/v1/admin/monitor) for real-time log streaming and metric broadcasting.

For exhaustive endpoint definitions, request and response schemas, and interactive parameter specifications, see the Engine API Reference or visit the Engine Reference Hub for a list of all published versions.

4. App API (/api/v1/{appId}/*)

The App API is the primary programmatic interface for end-users, external services, and business automations. It serves as the unified namespace for all functionality and domain models provided by installed Niksphere applications.

4.1 Symbol Execution API (RPC)

The Execution API enables direct remote procedure calls (RPC) on Pascal routines defined inside installed Niksphere Apps. It allows external clients, integrations, and frontend runtimes to invoke application logic on the server via standardized HTTP requests.

• Route Pattern: POST /api/v1/{appId}/{unitName}/{symbolName}
• Addressing Scheme: Routines are uniquely identified by combining the application ID, the unit name, and the procedure or function name.

Request & Response Structure

Clients pass arguments as an ordered JSON array in the request body (args). The Engine automatically maps standard JSON data types (integers, floats, strings, booleans, arrays, records) to the corresponding Pascal routine parameters:

Request:

POST /api/v1/de.niksphere.businessfundamentals/LanguageEntity/AddNumbers
Content-Type: application/json
Authorization: Bearer <JWT_ACCESS_TOKEN>

{
  "args": [10, 25]
}

Response (200 OK):

{
  "result": 35
}

Scope & Boundaries

In the current release, the Execution API is scoped to top-level procedures and functions defined in Pascal units. When invoking a function, the return value is serialized into the standard result envelope. Procedures without a return value complete with a standard success status.

4.2 Data Operations & Entity Access (Architectural Roadmap)

The architectural vision of the App API extends beyond logic execution: it is designed to be the complete gateway to an application's domain model, encompassing both business logic and data persistence.

In upcoming platform iterations, the App API will provide standardized, declarative data endpoints for CRUD and query operations directly against Pascal-defined entities:

[Table('k9m8n7p6q5'), Caption('Language')]
type Language = managed class(Entity)
public
    [Field('k9m8n7p6q6'), Caption('Language Code'), Required]
    var Code: string[10];
    [Field('k9m8n7p6q7'), Caption('Native Name'), Required]
    var Name: string[100];
end;

5. Client API (/api/v1/client)

The Client API is a high-throughput, low-latency communication layer designed exclusively for official interactive user interfaces (such as the Niksphere Web UI and future frontend client runtimes). It is a strictly internal protocol interface and is not intended for direct consumption or integration by third parties.

Operating over persistent, bidirectional WebSocket connections, the Client API handles real-time state synchronization, interactive user session management, push notifications, and live domain events. Connections are authorized using short-lived, single-use ticket tokens issued by the embedded IDP Broker, ensuring secure connection establishment without passing long-lived credentials in WebSocket headers. Furthermore, whenever applications are installed, updated, or recompiled, the Engine automatically broadcasts reset signals across active client sessions to trigger seamless UI cache invalidation and state re-synchronization.

6. Authentication & Protocol Conventions

The Niksphere Engine implements strict protocol standards and uniform response envelopes across all endpoints.

Authentication Matrix

Interface	Transport Protocol	Authentication Mechanism	Scope
System API	HTTP REST (/api/v1/health)	None (Unauthenticated)	Operational / Public
Admin API	HTTP REST	OIDC Bearer JWT (Authorization: Bearer <token>)	Administrator privilege
Admin API (Monitor)	WebSocket (/monitor)	One-Time Ticket Token (?ticket=<ticket_id>)	Administrator privilege
App API	HTTP REST	OIDC Bearer JWT (Authorization: Bearer <token>)	User / Service account
Client API	WebSocket (/client)	One-Time Ticket Token (?ticket=<ticket_id>)	Interactive user session

Standard Response Envelopes

• Successful Result Envelope:

  {
    "result": 42
  }

• Successful Data Envelope:

  {
    "data": {
      "id": "de.niksphere.base",
      "version": "1.0.0"
    }
  }

• Standard Error Envelope:

  {
    "error": "Symbol not found",
    "details": "The routine 'CalculateTax' is not exported by unit 'tax.pas'"
  }

HTTP Status Code Conventions

• 200 OK: Request succeeded and returned a payload.
• 201 Created: Resource successfully created.
• 204 No Content: Action succeeded with no payload returned.
• 400 Bad Request: Payload validation failed or invalid arguments provided.
• 401 Unauthorized: Missing, expired, or invalid authentication token.
• 403 Forbidden: Authenticated user lacks permission for this action.
• 404 Not Found: Requested app, entity, symbol, or version does not exist.
• 500 Internal Server Error: Unhandled server or runtime execution failure.

Related Documentation

• Product Overview & Vision — Architectural vision and platform overview.
• Layer System ("Everything is an App") — The 4 customization layers and No-Code / Low-Code / Pro-Code principles.
• Engine Database Architecture — Multi-database isolation (authDB, engineDB, tenantDB) and dual-driver storage.
• Engine Authentication Architecture — Embedded IDP Broker, external OIDC federation, and token lifespans.
• Engine API Reference — Detailed endpoint specifications and OpenAPI schemas.