feat(api): add Django Ninja with releng releases endpoint

Introduces the api/ Django app with django-ninja==1.6.2. Mounts
NinjaAPI at /api/ with OpenAPI schema at /api/openapi.json and
Swagger UI at /api/docs/. Implements the first route:

  GET /api/v1/releng/releases/ -> ReleasesSchema

Pydantic schema mirrors ReleaseJSONEncoder output. 10 tests
covering endpoint behaviour and OpenAPI schema contract.

Closes part of #199.

Signed-off-by: Leonidas Spyropoulos <artafinde@archlinux.org>

Author: inglor

api/__init__.py

@@ -0,0 +1,5 @@
+from django.apps import AppConfig
+
+
+class ApiConfig(AppConfig):
+    name = 'api'

api/apps.py

@@ -0,0 +1,13 @@
+from ninja import NinjaAPI
+
+from api.routes import releng
+
+api = NinjaAPI(
+    version="1",
+    title="Archweb API",
+    description="Arch Linux web API",
+    openapi_url="/openapi.json",
+    docs_url="/docs/",
+)
+
+api.add_router("/v1/releng/", releng.router)

api/router.py

@@ -0,0 +1,44 @@
+from django.urls import reverse
+from ninja import Router
+
+from api.schemas.releng import ReleaseSchema, ReleasesSchema
+from releng.models import Release
+
+router = Router(tags=["releng"])
+
+
+def _release_to_schema(release: Release) -> ReleaseSchema:
+    return ReleaseSchema(
+        version=release.version,
+        kernel_version=release.kernel_version or None,
+        release_date=release.release_date,
+        available=release.available,
+        info=release.info,
+        iso_url='/' + release.iso_url(),
+        magnet_uri=release.magnet_uri(),
+        torrent_url=reverse('releng-release-torrent', args=[release.version]),
+        md5_sum=release.md5_sum or None,
+        sha1_sum=release.sha1_sum or None,
+        sha256_sum=release.sha256_sum or None,
+        b2_sum=release.b2_sum or None,
+        wkd_email=release.wkd_email or None,
+        pgp_fingerprint=release.pgp_key or None,
+        created=release.created,
+        last_modified=release.last_modified,
+    )
+
+
+@router.get("/releases/", response=ReleasesSchema, url_name="releng-releases")
+def releases(request):
+    all_releases = Release.objects.all()
+    try:
+        latest_version = Release.objects.filter(available=True).values_list(
+            'version', flat=True).latest()
+    except Release.DoesNotExist:
+        latest_version = None
+
+    return ReleasesSchema(
+        version=1,
+        releases=[_release_to_schema(r) for r in all_releases],
+        latest_version=latest_version,
+    )

api/routes/__init__.py

@@ -0,0 +1,29 @@
+from datetime import date, datetime
+from typing import Optional
+
+from ninja import Schema
+
+
+class ReleaseSchema(Schema):
+    version: str
+    kernel_version: Optional[str] = None
+    release_date: date
+    available: bool
+    info: str
+    iso_url: Optional[str] = None
+    magnet_uri: Optional[str] = None
+    torrent_url: Optional[str] = None
+    md5_sum: Optional[str] = None
+    sha1_sum: Optional[str] = None
+    sha256_sum: Optional[str] = None
+    b2_sum: Optional[str] = None
+    wkd_email: Optional[str] = None
+    pgp_fingerprint: Optional[str] = None
+    created: datetime
+    last_modified: datetime
+
+
+class ReleasesSchema(Schema):
+    version: int
+    releases: list[ReleaseSchema]
+    latest_version: Optional[str] = None

api/routes/releng.py

@@ -0,0 +1,67 @@
+from datetime import datetime, timezone
+
+import pytest
+
+from releng.models import Release
+
+VERSION = '2025.05.01'
+KERNEL_VERSION = '6.9'
+
+
+@pytest.fixture
+def release(db):
+    r = Release.objects.create(
+        release_date=datetime.now(timezone.utc),
+        version=VERSION,
+        kernel_version=KERNEL_VERSION,
+        available=True,
+    )
+    yield r
+    r.delete()
+
+
+def test_releases_empty(db, client):
+    response = client.get('/api/v1/releng/releases/')
+    assert response.status_code == 200
+    data = response.json()
+    assert data['version'] == 1
+    assert data['releases'] == []
+    assert data['latest_version'] is None
+
+
+def test_releases_returns_release_fields(client, release):
+    response = client.get('/api/v1/releng/releases/')
+    assert response.status_code == 200
+    r = response.json()['releases'][0]
+    assert r['version'] == VERSION
+    assert r['kernel_version'] == KERNEL_VERSION
+    assert r['available'] is True
+
+
+def test_releases_latest_version_is_newest_available(db, client):
+    now = datetime.now(timezone.utc)
+    Release.objects.create(release_date=now, version='2025.01.01', available=True)
+    Release.objects.create(release_date=now, version='2025.05.01', available=True)
+    data = client.get('/api/v1/releng/releases/').json()
+    assert data['latest_version'] == '2025.05.01'
+
+
+def test_releases_latest_version_excludes_unavailable(db, client):
+    now = datetime.now(timezone.utc)
+    Release.objects.create(release_date=now, version='2025.01.01', available=True)
+    Release.objects.create(release_date=now, version='2025.05.01', available=False)
+    data = client.get('/api/v1/releng/releases/').json()
+    assert data['latest_version'] == '2025.01.01'
+
+
+def test_releases_optional_fields_null_when_absent(db, client):
+    Release.objects.create(
+        release_date=datetime.now(timezone.utc),
+        version='2025.05.01',
+    )
+    r = client.get('/api/v1/releng/releases/').json()['releases'][0]
+    assert r['kernel_version'] is None
+    assert r['md5_sum'] is None
+    assert r['sha1_sum'] is None
+    assert r['sha256_sum'] is None
+    assert r['b2_sum'] is None

api/schemas/__init__.py

@@ -0,0 +1,41 @@
+"""OpenAPI schema contract tests for the Archweb API."""
+
+def test_openapi_schema_served(client):
+    response = client.get('/api/openapi.json')
+    assert response.status_code == 200
+    assert response['Content-Type'] == 'application/json'
+
+
+def test_openapi_schema_version(client):
+    schema = client.get('/api/openapi.json').json()
+    assert schema['openapi'].startswith('3.')
+    assert schema['info']['title'] == 'Archweb API'
+    assert schema['info']['version'] == '1'
+
+
+def test_openapi_releng_releases_endpoint_present(client):
+    paths = client.get('/api/openapi.json').json()['paths']
+    assert '/api/v1/releng/releases/' in paths
+    assert 'get' in paths['/api/v1/releng/releases/']
+
+
+def test_openapi_releases_schema_fields(client):
+    schema = client.get('/api/openapi.json').json()
+    components = schema['components']['schemas']
+    assert 'ReleasesSchema' in components
+    assert 'ReleaseSchema' in components
+
+    release_props = components['ReleaseSchema']['properties']
+    required_fields = {'version', 'release_date', 'available', 'info'}
+    assert required_fields <= release_props.keys()
+
+    nullable_fields = {'kernel_version', 'md5_sum', 'sha1_sum', 'sha256_sum', 'b2_sum'}
+    for field in nullable_fields:
+        assert field in release_props
+        types = {t.get('type') for t in release_props[field].get('anyOf', [])}
+        assert 'null' in types, f"{field} must be nullable"
+
+
+def test_openapi_docs_url_exists(client):
+    response = client.get('/api/docs/')
+    assert response.status_code == 200