feat: add API metadata endpoint

Author: NiklasTiede

app/main.py

@@ -15,7 +15,7 @@
     AllowedProgrammingLanguages,
     AllowedSpokenLanguages,
 )
-from app.schemas import Developer, HealthStatus, Repository
+from app.schemas import Developer, HealthStatus, Metadata, Repository
 from app.scraping import (
     UpstreamRequestError,
     get_request,
@@ -25,6 +25,8 @@
 )
 
 app = fastapi.FastAPI()
+APP_NAME = "Github Trending API"
+APP_VERSION = "1.0.2"
 CACHE_TTL_SECONDS = 300
 CacheKey = tuple[str, tuple[tuple[str, str], ...]]
 _trending_html_cache: dict[CacheKey, tuple[float, str]] = {}
@@ -107,6 +109,25 @@ def health() -> HealthStatus:
     return HealthStatus(status="ok")
 
 
+@app.get("/metadata", response_model=Metadata)
+def metadata(request: fastapi.Request) -> Metadata:
+    """Return API metadata for clients."""
+    base_url = str(request.base_url).rstrip("/")
+    return Metadata(
+        name=APP_NAME,
+        version=APP_VERSION,
+        docs=f"{base_url}/docs",
+        redoc=f"{base_url}/redoc",
+        health=f"{base_url}/health",
+        repositories=f"{base_url}/repositories",
+        developers=f"{base_url}/developers",
+        cacheTtlSeconds=CACHE_TTL_SECONDS,
+        supportedDateRanges=[date_range.value for date_range in AllowedDateRanges],
+        supportedProgrammingLanguagesCount=len(AllowedProgrammingLanguages),
+        supportedSpokenLanguagesCount=len(AllowedSpokenLanguages),
+    )
+
+
 @app.get("/repositories", response_model=list[Repository])
 async def trending_repositories(
     since: AllowedDateRanges | None = None,

app/schemas.py

@@ -8,6 +8,22 @@ class HealthStatus(BaseModel):
     status: str
 
 
+class Metadata(BaseModel):
+    """API metadata response data."""
+
+    name: str
+    version: str
+    docs: str
+    redoc: str
+    health: str
+    repositories: str
+    developers: str
+    cacheTtlSeconds: int
+    supportedDateRanges: list[str]
+    supportedProgrammingLanguagesCount: int
+    supportedSpokenLanguagesCount: int
+
+
 class Contributor(BaseModel):
     """Repository contributor data."""
 

tests/main_test.py

@@ -43,6 +43,26 @@ def test_health_route():
     assert response.json() == {"status": "ok"}
 
 
+def test_metadata_route():
+    """Tests if the metadata route returns API discovery data."""
+    response = client.get("/metadata")
+
+    assert response.status_code == 200
+    assert response.json() == {
+        "name": "Github Trending API",
+        "version": "1.0.2",
+        "docs": "http://testserver/docs",
+        "redoc": "http://testserver/redoc",
+        "health": "http://testserver/health",
+        "repositories": "http://testserver/repositories",
+        "developers": "http://testserver/developers",
+        "cacheTtlSeconds": 300,
+        "supportedDateRanges": ["daily", "weekly", "monthly"],
+        "supportedProgrammingLanguagesCount": len(main.AllowedProgrammingLanguages),
+        "supportedSpokenLanguagesCount": len(main.AllowedSpokenLanguages),
+    }
+
+
 def test_repositories_route_uses_query_parameters(monkeypatch):
     """Tests the repository endpoint request payload and response parsing."""
     calls = []