# DS2API Health Check Endpoints: Liveness and Readiness Probes Explained

> Discover DS2API health check endpoints. Learn how /healthz and /readyz probes ensure your service is operational with JSON status payloads.

- Repository: [CJACK./ds2api](https://github.com/CJackHwang/ds2api)
- Tags: deep-dive
- Published: 2026-04-26

---

**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:

```json
{"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:

```json
{"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`](https://github.com/CJackHwang/ds2api/blob/main/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:

```go
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`](https://github.com/CJackHwang/ds2api/blob/main/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:

```bash

# 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:

```go
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`](https://github.com/CJackHwang/ds2api/blob/main/router_health_test.go), DS2API utilizes these health check endpoints within its integration testing framework. The file **[`internal/testsuite/runner_env.go`](https://github.com/CJackHwang/ds2api/blob/main/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`](https://github.com/CJackHwang/ds2api/blob/main/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`](https://github.com/CJackHwang/ds2api/blob/main/internal/server/router.go)** (lines 80-93) with tests in [`internal/server/router_health_test.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/server/router_health_test.go).
- These endpoints are exercised during integration testing via [`internal/testsuite/runner_env.go`](https://github.com/CJackHwang/ds2api/blob/main/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`](https://github.com/CJackHwang/ds2api/blob/main/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`](https://github.com/CJackHwang/ds2api/blob/main/internal/server/router_health_test.go)**, which verify HTTP 200 responses for both paths. Additionally, integration tests in [`internal/testsuite/runner_env.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/testsuite/runner_env.go) and [`internal/testsuite/runner_cases_openai.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/testsuite/runner_cases_openai.go) exercise these endpoints during actual test suite execution to ensure operational reliability.