DS2API Health Check Endpoints: Liveness and Readiness Probes Explained

DS2API exposes two standard health check endpoints—/healthz for liveness and /readyz for readiness—that return HTTP 200 with JSON status payloads when the service is operational.

DS2API implements Kubernetes-compatible health check endpoints to support monitoring and load balancer configurations. The repository provides dedicated HTTP routes that distinguish between process liveness and application readiness, enabling precise orchestration health checks. Understanding these DS2API health check endpoints is essential for operators deploying the service in containerized environments.

Available Health Check Endpoints

DS2API provides two distinct endpoints following cloud-native conventions for container health monitoring. Both routes respond to GET and HEAD requests and return JSON content with an HTTP 200 status when healthy.

Liveness Probe: /healthz

The /healthz endpoint serves as a liveness probe that indicates whether the server process is alive and able to respond to HTTP requests. When queried, it returns a JSON payload with an ok status:

{"status":"ok"}

This endpoint is ideal for Kubernetes liveness probes that restart containers when the application becomes unresponsive.

Readiness Probe: /readyz

The /readyz endpoint functions as a readiness probe, returning a ready status only when the server has completed its startup sequence. This includes finishing configuration loading and initializing dependent services. The endpoint returns:

{"status":"ready"}

Load balancers use this signal to determine when the instance is prepared to accept traffic, preventing premature request routing during startup.

Implementation in internal/server/router.go

According to the DS2API source code, the health check handlers are defined in internal/server/router.go at lines 80-89. These handlers configure the HTTP response by setting the Content-Type to application/json, writing an HTTP 200 status code, and encoding the JSON payload to the response writer.

The router registration occurs immediately after the handler definitions, at lines 90-93:

r.Get("/healthz", healthzHandler)
r.Head("/healthz", healthzHandler)
r.Get("/readyz", readyzHandler)
r.Head("/readyz", readyzHandler)

This registration maps both healthzHandler and readyzHandler to their respective paths, supporting both GET and HEAD HTTP methods. The unit tests in internal/server/router_health_test.go (lines 18-22) verify that these endpoints return the expected successful responses.

Testing the Endpoints

You can verify DS2API health check endpoints using standard HTTP clients or the provided test suite.

Using curl

For quick validation from the command line:

# Check liveness

curl -s http://localhost:8080/healthz

# Check readiness

curl -s http://localhost:8080/readyz

# Verify HTTP status codes only

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/healthz

Both commands return 200 when the service is healthy.

Go Client Integration

To programmatically check health status from a Go application:

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

type healthResp struct {
	Status string `json:"status"`
}

func checkHealth(url string) error {
	resp, err := http.Get(url)
	if err != nil {
		return err
	}
	defer resp.Body.Close()

	var h healthResp
	if err := json.NewDecoder(resp.Body).Decode(&h); err != nil {
		return err
	}
	fmt.Printf("%s → %s (HTTP %d)\n", url, h.Status, resp.StatusCode)
	return nil
}

func main() {
	checkHealth("http://localhost:8080/healthz")
	checkHealth("http://localhost:8080/readyz")
}

Integration Test Coverage

Beyond unit tests in router_health_test.go, DS2API utilizes these health check endpoints within its integration testing framework. The file internal/testsuite/runner_env.go leverages both /healthz and /readyz as part of the test runner environment setup, while internal/testsuite/runner_cases_openai.go demonstrates client requests to the health endpoints during OpenAI test case execution. This ensures the health checks function correctly under realistic operational conditions.

Summary

• DS2API provides two standard health check endpoints: /healthz for liveness and /readyz for readiness.
• Both endpoints support GET and HEAD methods and return HTTP 200 with JSON status payloads.
• /healthz returns {"status":"ok"} to indicate the server process is alive.
• /readyz returns {"status":"ready"} when the server has completed startup and is ready to accept traffic.
• Implementation resides in internal/server/router.go (lines 80-93) with tests in internal/server/router_health_test.go.
• These endpoints are exercised during integration testing via internal/testsuite/runner_env.go.

Frequently Asked Questions

What is the difference between /healthz and /readyz in DS2API?

The /healthz endpoint acts as a liveness probe, returning {"status":"ok"} when the server process is running and responsive. The /readyz endpoint serves as a readiness probe, returning {"status":"ready"} only after the server has fully initialized its configuration and dependencies, indicating it is ready to serve traffic.

Which HTTP methods are supported by DS2API health check endpoints?

Both the /healthz and /readyz endpoints support GET and HEAD HTTP methods. This allows lightweight health checks using HEAD requests that return headers without a body, reducing network overhead for monitoring systems.

Where are the health check handlers implemented in the DS2API source code?

The health check handlers are defined and registered in internal/server/router.go at lines 80-93. The healthzHandler and readyzHandler functions write the JSON responses, while the router registration maps both GET and HEAD methods to these handlers.

How does DS2API test its health check endpoints?

DS2API validates the health check endpoints through unit tests in internal/server/router_health_test.go, which verify HTTP 200 responses for both paths. Additionally, integration tests in internal/testsuite/runner_env.go and internal/testsuite/runner_cases_openai.go exercise these endpoints during actual test suite execution to ensure operational reliability.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}