api: add health endpoint for availability checks

The root endpoint now serves the HTML landing page, so it should not be documented or tested as the machine-readable API availability check.

Add GET /health for a stable JSON health response, update the root handler tests to assert the HTML contract, add health endpoint coverage, and point the local-instance docs at /latest/health.

Fixes: #632
Signed-off-by: Denys Fedoryshchenko <denys.f@collabora.com>

Author: nuclearcat

api/main.py

@@ -298,6 +298,13 @@ async def root():
         return HTMLResponse(file.read())
 
 
+@app.get("/health")
+async def health():
+    """Health endpoint handler"""
+    metrics.add("http_requests_total", 1)
+    return {"status": "ok", "service": "KernelCI API"}
+
+
 # -----------------------------------------------------------------------------
 # Users
 

doc/local-instance.md

@@ -89,8 +89,8 @@ It can take a few minutes to build the images from scratch the first time.
 Then the services should be up and running.  To confirm the API is available:
 
 ```
-$ curl http://localhost:8001/latest/
-{"message":"KernelCI API"}
+$ curl http://localhost:8001/latest/health
+{"status":"ok","service":"KernelCI API"}
 ```
 
 > **Port numbers** for the services exposed by `docker-compose` can be
@@ -101,7 +101,7 @@ $ curl http://localhost:8001/latest/
 Following the `curl` command from the example above, the container log should
 show:
 ```
-kernelci-api | INFO:     172.20.0.1:49228 - "GET / HTTP/1.1" 200 OK
+kernelci-api | INFO:     172.20.0.1:49228 - "GET /latest/health HTTP/1.1" 200 OK
 ```
 
 ### Bootstrap the initial admin user

tests/e2e_tests/test_root_handler.py

@@ -13,4 +13,16 @@ async def test_root_endpoint(test_async_client):
     """Test root handler"""
     response = await test_async_client.get("/")
     assert response.status_code == 200
-    assert response.json() == {"message": "KernelCI API"}
+    assert response.headers["content-type"].startswith("text/html")
+    assert "KernelCI API Server" in response.text
+
+
+@pytest.mark.asyncio
+async def test_health_endpoint(test_async_client):
+    """Test health handler"""
+    response = await test_async_client.get("health")
+    assert response.status_code == 200
+    assert response.json() == {
+        "status": "ok",
+        "service": "KernelCI API",
+    }

tests/unit_tests/test_root_handler.py

@@ -11,8 +11,24 @@ def test_root_endpoint(test_client):
     Test Case : Test KernelCI API root endpoint
     Expected Result :
         HTTP Response Code 200 OK
-        JSON with 'message' key
+        HTML landing page
     """
     response = test_client.get("/")
     assert response.status_code == 200
-    assert response.json() == {"message": "KernelCI API"}
+    assert response.headers["content-type"].startswith("text/html")
+    assert "KernelCI API Server" in response.text
+
+
+def test_health_endpoint(test_client):
+    """
+    Test Case : Test KernelCI API health endpoint
+    Expected Result :
+        HTTP Response Code 200 OK
+        JSON with health status
+    """
+    response = test_client.get("health")
+    assert response.status_code == 200
+    assert response.json() == {
+        "status": "ok",
+        "service": "KernelCI API",
+    }