System API Specification

Overview

The System API provides health check and readiness endpoints for load balancer integration and operational monitoring.

Base Path: /system

Content Types: - Request: application/json - Response: application/json

Response Format

All endpoints return a TlinqApiResponse object:

{
  "apiStatus": {
    "errorCode": "OK",
    "errorMessage": "Success"
  },
  "apiData": { ... }
}

---

Endpoints

POST /system/health

Deep health check that verifies all critical subsystems.

Access: guest, agent, admin

Request Body: Empty JSON object {}

Response (HTTP 200 — Healthy):

{
  "apiStatus": {
    "errorCode": "OK",
    "errorMessage": "Success"
  },
  "apiData": {
    "database": "UP",
    "cluster": "UP (2 members)",
    "plugins": "INITIALIZED",
    "status": "UP"
  }
}

Response (HTTP 503 — Degraded):

{
  "apiStatus": {
    "errorCode": "OK",
    "errorMessage": "Success"
  },
  "apiData": {
    "database": "DOWN: Connection refused",
    "cluster": "UP (1 members)",
    "clusterWarning": "Single-node cluster — no redundancy",
    "plugins": "INITIALIZED",
    "status": "DEGRADED"
  }
}

Checks Performed:

Check	Field	UP	DOWN
Database connectivity	database	SELECT 1 succeeds	Connection error message
Hazelcast cluster	cluster	Member count shown	Connection error message
Plugin initialization	plugins	INITIALIZED	NOT_INITIALIZED

If the cluster has only 1 member, a clusterWarning field is added.

The overall status is UP only if all checks pass. If any check fails, it becomes DEGRADED and the HTTP status is 503.

Load Balancer Configuration:

Configure the health check to call POST /system/health with an empty JSON body. Mark the instance as unhealthy on HTTP 503 responses.

---

POST /system/ready

Lightweight readiness probe that checks whether all plugins have been initialized.

Access: guest, agent, admin

Request Body: Empty JSON object {}

Response (HTTP 200 — Ready):

{
  "apiStatus": {
    "errorCode": "OK",
    "errorMessage": "Success"
  },
  "apiData": {
    "ready": true
  }
}

Response (HTTP 503 — Not Ready):

{
  "apiStatus": {
    "errorCode": "OK",
    "errorMessage": "Success"
  },
  "apiData": {
    "ready": false
  }
}

Use Case:

Use this endpoint during rolling deployments to delay traffic until the instance has fully initialized. The readiness probe returns 503 while plugins are loading and 200 once initialization is complete.

---

Response Headers

All API responses include the following headers:

Header	Description
X-Correlation-ID	Request correlation ID for distributed tracing. Either propagated from the request header or auto-generated as an 8-character UUID.

To trace a request across instances, pass X-Correlation-ID in the request header. The same value will be returned in the response and logged on the server.