ENH: Add health check model and responses

Author: mferrera

src/fmu_settings_api/__main__.py

@@ -8,6 +8,7 @@
 from starlette.middleware.cors import CORSMiddleware
 
 from .config import settings
+from .models import HealthCheck
 from .v1.main import api_v1_router
 
 
@@ -24,10 +25,19 @@ def custom_generate_unique_id(route: APIRoute) -> str:
 app.include_router(api_v1_router)
 
 
-@app.get("/health", tags=["app"])
-async def health_check() -> dict[str, str]:
+@app.get(
+    "/health",
+    tags=["app"],
+    response_model=HealthCheck,
+    summary="A health check on the application",
+    description=(
+        "This route requires no form of authentication or authorization. "
+        "It can be used to check if the application is running and responsive."
+    ),
+)
+async def health_check() -> HealthCheck:
     """Simple health check endpoint."""
-    return {"status": "ok"}
+    return HealthCheck()
 
 
 def run_server(

src/fmu_settings_api/models/__init__.py

@@ -1,6 +1,13 @@
 """Models used for messages and responses at API endpoints."""
 
-from .common import APIKey, Message, SessionResponse
+from .common import APIKey, HealthCheck, Message, SessionResponse
 from .project import FMUDirPath, FMUProject
 
-__all__ = ["FMUDirPath", "FMUProject", "Message", "SessionResponse", "APIKey"]
+__all__ = [
+    "APIKey",
+    "FMUDirPath",
+    "FMUProject",
+    "HealthCheck",
+    "Message",
+    "SessionResponse",
+]

src/fmu_settings_api/models/common.py

@@ -1,11 +1,19 @@
 """Common response models from the API."""
 
+from typing import Literal
+
 from fmu.settings.models.user_config import UserConfig
 from pydantic import BaseModel, SecretStr
 
 from .project import FMUProject
 
 
+class HealthCheck(BaseModel):
+    """Returns "ok" if the route is functioning correctly."""
+
+    status: Literal["ok"] = "ok"
+
+
 class SessionResponse(BaseModel):
     """Information returned when a session is initially created."""
 

src/fmu_settings_api/v1/main.py

@@ -14,11 +14,12 @@
     get_session,
     verify_auth_token,
 )
-from fmu_settings_api.models import FMUProject, SessionResponse
+from fmu_settings_api.models import FMUProject, HealthCheck, SessionResponse
 from fmu_settings_api.session import (
     add_fmu_project_to_session,
     create_fmu_session,
 )
+from fmu_settings_api.v1.responses import GetSessionResponses
 
 from .routes import project, user
 
@@ -28,10 +29,20 @@
 api_v1_router.include_router(user.router, dependencies=[Depends(get_session)])
 
 
-@api_v1_router.get("/health", dependencies=[Depends(get_session)])
-async def v1_health_check() -> dict[str, str]:
+@api_v1_router.get(
+    "/health",
+    response_model=HealthCheck,
+    dependencies=[Depends(get_session)],
+    summary="A health check on the /v1 routes.",
+    description=(
+        "This route requires a valid session to return 200 OK. it can used to "
+        "check if the user has a valid session."
+    ),
+    responses=GetSessionResponses,
+)
+async def v1_health_check() -> HealthCheck:
     """Simple health check endpoint."""
-    return {"status": "ok"}
+    return HealthCheck()
 
 
 @api_v1_router.post(

src/fmu_settings_api/v1/responses.py

@@ -0,0 +1,30 @@
+"""Contains mappings of responses that API end points return."""
+
+from typing import Any, Final, TypeAlias
+
+Responses: TypeAlias = dict[int | str, dict[str, Any]]
+
+GetSessionResponses: Final[Responses] = {
+    401: {
+        "description": "No active or valid session was found",
+        "content": {
+            "application/json": {
+                "example": {
+                    "examples": [
+                        {"detail": "No active session found"},
+                        {"detail": "Invalid or expired session"},
+                        {"detail": "No FMU project directory open"},
+                    ],
+                },
+            },
+        },
+    },
+    500: {
+        "description": "Something unexpected has happened",
+        "content": {
+            "application/json": {
+                "example": {"detail": "Session error: {string content of exception}"},
+            },
+        },
+    },
+}

tests/test_main.py

@@ -4,6 +4,7 @@
 from fastapi.testclient import TestClient
 
 from fmu_settings_api.__main__ import app
+from fmu_settings_api.models import HealthCheck
 
 client = TestClient(app)
 
@@ -15,5 +16,6 @@ def test_main_invocation() -> None:
 def test_health_check() -> None:
     """Test the health check endpoint."""
     response = client.get("/health")
-    assert response.status_code == status.HTTP_200_OK
+    assert response.status_code == status.HTTP_200_OK, response.json()
     assert response.json() == {"status": "ok"}
+    assert HealthCheck() == HealthCheck.model_validate(response.json())

tests/test_v1/test_health.py

@@ -5,6 +5,7 @@
 
 from fmu_settings_api.__main__ import app
 from fmu_settings_api.config import settings
+from fmu_settings_api.models import HealthCheck
 
 client = TestClient(app)
 
@@ -14,30 +15,31 @@
 def test_health_check_no_session() -> None:
     """Test the health check endpoint with missing token and no session."""
     response = client.get(ROUTE)
-    assert response.status_code == status.HTTP_401_UNAUTHORIZED
+    assert response.status_code == status.HTTP_401_UNAUTHORIZED, response.json()
     assert response.json() == {"detail": "No active session found"}
 
 
 def test_health_check_no_session_bad_token() -> None:
     """Test the health check endpoint with an invalid token but no session."""
     token = "no" * 32
     response = client.get(ROUTE, headers={settings.TOKEN_HEADER_NAME: token})
-    assert response.status_code == status.HTTP_401_UNAUTHORIZED
+    assert response.status_code == status.HTTP_401_UNAUTHORIZED, response.json()
     assert response.json() == {"detail": "No active session found"}
 
 
 def test_health_check_no_session_valid_token(mock_token: str) -> None:
     """Test the health check endpoint with a valid token but no session."""
     response = client.get(ROUTE, headers={settings.TOKEN_HEADER_NAME: mock_token})
-    assert response.status_code == status.HTTP_401_UNAUTHORIZED
+    assert response.status_code == status.HTTP_401_UNAUTHORIZED, response.json()
     assert response.json() == {"detail": "No active session found"}
 
 
 def test_health_check_no_session_valid_session(client_with_session: TestClient) -> None:
     """Test the health check endpoint with a valid session."""
     response = client_with_session.get(ROUTE)
-    assert response.status_code == status.HTTP_200_OK
+    assert response.status_code == status.HTTP_200_OK, response.json()
     assert response.json() == {"status": "ok"}
+    assert HealthCheck() == HealthCheck.model_validate(response.json())
 
 
 def test_health_check_no_session_valid_session_invalid_token(
@@ -48,8 +50,9 @@ def test_health_check_no_session_valid_session_invalid_token(
     response = client_with_session.get(
         ROUTE, headers={settings.TOKEN_HEADER_NAME: token}
     )
-    assert response.status_code == status.HTTP_200_OK
+    assert response.status_code == status.HTTP_200_OK, response.json()
     assert response.json() == {"status": "ok"}
+    assert HealthCheck() == HealthCheck.model_validate(response.json())
 
 
 def test_health_check_no_session_valid_session_valid_token(
@@ -59,5 +62,6 @@ def test_health_check_no_session_valid_session_valid_token(
     response = client_with_session.get(
         ROUTE, headers={settings.TOKEN_HEADER_NAME: mock_token}
     )
-    assert response.status_code == status.HTTP_200_OK
+    assert response.status_code == status.HTTP_200_OK, response.json()
     assert response.json() == {"status": "ok"}
+    assert HealthCheck() == HealthCheck.model_validate(response.json())