Clarify or redesign fixed `ok` status in Admin API health response

[kayx23]

Summary

GET /admin/v1/health returns a top-level status field that is currently always "ok" on successful responses. This can be confusing because the field name looks like it might summarize gateway or model health, while the actionable health signal is actually in models[].health and config.

Current behavior

Verified against latest origin/main at fd164ba:

• crates/aisix-admin/src/health_handler.rs defines HealthResponse.status as &'static str.
• get_health always returns status: "ok" when the endpoint succeeds.
• The OpenAPI schema exposes HealthResponse.status as an enum with only "ok".
• Other Admin API response schemas do not generally return {"status":"ok"}. This appears scoped to GET /admin/v1/health.
• GET /admin/v1/models/status also has a status field, but that one is a real runtime enum: healthy, unhealthy, cooldown, not_applicable.

Why this matters

For users reading the Admin API reference, a top-level status field in a health response naturally suggests an aggregate health result. Since it is fixed to "ok", clients could mistakenly treat the response as healthy even when individual models are degraded/down or configuration freshness is stale.

Short-term documentation

The current Admin API OpenAPI documentation update clarifies this behavior by describing status as a fixed success marker and directing users to models[].health and config for actionable health details.

Remaining product/API question

Decide whether the current response shape should remain the long-term contract, or whether a future API shape should change it. Possible directions:

• Keep status as a documented fixed success marker.
• Deprecate or remove the top-level status field if it is only a success marker.
• Make status a real aggregate derived from model health and configuration freshness.

This is not urgent, but it would be good to decide the intended contract before more users depend on the Admin API shape.

[coderabbitai]

🔗 Related PRs

#563 - feat: timeout-triggered fallback (timeout + stream_timeout) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!