Merge pull request #795 from seapagan/feature/heartbeat-endpoint

Add heartbeat endpoint and tests

Author: seapagan

README.md

@@ -129,6 +129,7 @@ following advantages to starting your own from scratch :
   when new users register. The content is set by a template (currently a basic
   placeholder). This email has a link for the user to confirm their email
   address - until this is done, the user cannot user the API.
+- A lightweight `/heartbeat` endpoint for uptime/health checks.
 - Docker and Compose file set up to develop and test this API using Docker
 
 **This template is still in very active development and probably not yet ready

app/resources/heartbeat.py

@@ -0,0 +1,11 @@
+"""Routes for service health checks."""
+
+from fastapi import APIRouter
+
+router = APIRouter(tags=["Health"])
+
+
+@router.get("/heartbeat", summary="Simple uptime probe")
+def heartbeat() -> dict[str, str]:
+    """Return a minimal response to show the service is up."""
+    return {"status": "ok"}

app/resources/routes.py

@@ -3,13 +3,14 @@
 from fastapi import APIRouter
 
 from app.config.settings import get_settings
-from app.resources import api_key, auth, home, user
+from app.resources import api_key, auth, heartbeat, home, user
 
 api_router = APIRouter(prefix=get_settings().api_root)
 
 api_router.include_router(user.router)
 api_router.include_router(auth.router)
 api_router.include_router(api_key.router)
+api_router.include_router(heartbeat.router)
 
 if not get_settings().no_root_route:
     api_router.include_router(home.router)

docs/reference/api.md

@@ -824,6 +824,24 @@ Delete another user's API key.
 
 ---
 
+## Health Endpoints
+
+### Heartbeat
+
+**Endpoint:** `GET /heartbeat`
+
+Returns a minimal response to confirm the service is up.
+
+**Response:** `200 OK`
+
+```json
+{
+  "status": "ok"
+}
+```
+
+---
+
 ## Authentication Methods
 
 The API supports two authentication methods:

tests/integration/test_home_routes.py

@@ -31,3 +31,10 @@ async def test_favicon(self, client) -> None:
         assert response.headers["content-type"] == "image/vnd.microsoft.icon"
         # Ensure we actually got some content
         assert len(response.content) > 0
+
+    @pytest.mark.asyncio
+    async def test_heartbeat(self, client) -> None:
+        """Test the heartbeat route returns a simple OK payload."""
+        response = await client.get("/heartbeat")
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json() == {"status": "ok"}