Feature: New APIs

docker/requirements.txt

@@ -12,6 +12,10 @@ async-timeout==4.0.2
     # via redis
 atomicwrites==1.4.1
     # via promgen (pyproject.toml)
+attrs==26.1.0
+    # via
+    #   jsonschema
+    #   referencing
 billiard==3.6.4.0
     # via celery
 celery[redis]==5.2.7
@@ -49,6 +53,7 @@ django==4.2.26
     #   django-filter
     #   django-guardian
     #   djangorestframework
+    #   drf-spectacular
     #   promgen (pyproject.toml)
     #   social-auth-app-django
 django-environ==0.10.0
@@ -58,11 +63,21 @@ django-filter==23.2
 django-guardian==3.0.0
     # via promgen (pyproject.toml)
 djangorestframework==3.14.0
+    # via
+    #   drf-spectacular
+    #   promgen (pyproject.toml)
+drf-spectacular==0.29.0
     # via promgen (pyproject.toml)
 gunicorn==22.0.0
     # via -r docker/requirements.in
 idna==3.7
     # via requests
+inflection==0.5.1
+    # via drf-spectacular
+jsonschema==4.25.1
+    # via drf-spectacular
+jsonschema-specifications==2025.9.1
+    # via jsonschema
 kombu==5.3.7
     # via
     #   celery
@@ -90,16 +105,26 @@ pytz==2023.3
     #   celery
     #   djangorestframework
 pyyaml==6.0.1
-    # via promgen (pyproject.toml)
+    # via
+    #   drf-spectacular
+    #   promgen (pyproject.toml)
 redis==4.6.0
     # via celery
+referencing==0.36.2
+    # via
+    #   jsonschema
+    #   jsonschema-specifications
 requests==2.32.2
     # via
     #   promgen (pyproject.toml)
     #   requests-oauthlib
     #   social-auth-core
 requests-oauthlib==1.3.1
     # via social-auth-core
+rpds-py==0.27.1
+    # via
+    #   jsonschema
+    #   referencing
 sentry-sdk==1.19.1
     # via -r docker/requirements.in
 six==1.16.0
@@ -113,7 +138,11 @@ sqlparse==0.5.0
 typing-extensions==4.7.1
     # via
     #   asgiref
+    #   drf-spectacular
     #   kombu
+    #   referencing
+uritemplate==4.2.0
+    # via drf-spectacular
 urllib3==2.2.0
     # via
     #   requests

promgen/filters.py

@@ -1,4 +1,8 @@
 import django_filters
+from django.contrib.auth.models import User
+from django.contrib.contenttypes.models import ContentType
+
+from promgen import models
 
 
 class ShardFilter(django_filters.rest_framework.FilterSet):
@@ -22,5 +26,228 @@ class RuleFilter(django_filters.rest_framework.FilterSet):
 
 
 class FarmFilter(django_filters.rest_framework.FilterSet):
-    name = django_filters.CharFilter(field_name="name", lookup_expr="contains")
-    source = django_filters.CharFilter(field_name="source", lookup_expr="exact")
+    name = django_filters.CharFilter(
+        field_name="name",
+        lookup_expr="contains",
+        help_text="Filter by farm name containing a specific substring. Example: name=Example Farm",
+    )
+    source = django_filters.ChoiceFilter(
+        field_name="source",
+        choices=[(name, name) for name, _ in models.Farm.driver_set()],
+        lookup_expr="exact",
+        help_text="Filter by exact source name. Example: source=promgen",
+    )
+
+
+def filter_content_type(queryset, name, value):
+    try:
+        if value == "user":
+            content_type_id = ContentType.objects.get_for_model(User).id
+        else:
+            content_type_id = ContentType.objects.get(model=value, app_label="promgen").id
+        return queryset.filter(content_type_id=content_type_id)
+    except ContentType.DoesNotExist:
+        return queryset.none()
+
+
+class AuditFilter(django_filters.rest_framework.FilterSet):
+    object_id = django_filters.NumberFilter(
+        field_name="object_id",
+        lookup_expr="exact",
+        help_text="Filter by exact object ID. Example: object_id=123",
+    )
+    content_type = django_filters.ChoiceFilter(
+        field_name="content_type",
+        choices=[
+            ("service", "Service"),
+            ("project", "Project"),
+            ("rule", "Rule"),
+            ("sender", "Notifier"),
+            ("exporter", "Exporter"),
+            ("url", "URL"),
+            ("farm", "Farm"),
+            ("host", "Host"),
+        ],
+        method=filter_content_type,
+        help_text="Filter by content type model name. Example: content_type=service",
+    )
+    user = django_filters.CharFilter(
+        field_name="user__username",
+        lookup_expr="exact",
+        help_text="Filter by exact owner username. Example: owner=Example Owner",
+    )
+
+
+class NotifierFilter(django_filters.rest_framework.FilterSet):
+    sender = django_filters.ChoiceFilter(
+        field_name="sender",
+        choices=[(module_name, module_name) for module_name, _ in models.Sender.driver_set()],
+        help_text="Filter by sender type. Example: sender=promgen.notification.email",
+    )
+    value = django_filters.CharFilter(
+        field_name="value",
+        lookup_expr="contains",
+        help_text="Filter by value containing a specific substring. "
+        "Example: value=demo@example.com",
+    )
+    object_id = django_filters.NumberFilter(
+        field_name="object_id",
+        lookup_expr="exact",
+        help_text="Filter by exact object ID. Example: object_id=123",
+    )
+    content_type = django_filters.ChoiceFilter(
+        field_name="content_type",
+        choices=[
+            ("service", "Service"),
+            ("project", "Project"),
+            ("user", "User"),
+        ],
+        method=filter_content_type,
+        help_text="Filter by content type model name. Example: content_type=service",
+    )
+    owner = django_filters.CharFilter(
+        field_name="owner__username",
+        lookup_expr="exact",
+        help_text="Filter by exact owner username. Example: owner=Example Owner",
+    )
+
+
+class RuleFilterV2(django_filters.rest_framework.FilterSet):
+    name = django_filters.CharFilter(
+        field_name="name",
+        lookup_expr="contains",
+        help_text="Filter by rule name containing a specific substring. Example: name=Example Rule",
+    )
+    parent = django_filters.CharFilter(
+        field_name="parent__name",
+        lookup_expr="contains",
+        help_text="Filter by parent rule name containing a specific substring. "
+        "Example: parent=Example Parent",
+    )
+    enabled = django_filters.BooleanFilter(
+        field_name="enabled",
+        help_text="Filter by enabled status (true or false). Example: enabled=true",
+    )
+    object_id = django_filters.NumberFilter(
+        field_name="object_id",
+        lookup_expr="exact",
+        help_text="Filter by exact object ID. Example: object_id=123",
+    )
+    content_type = django_filters.ChoiceFilter(
+        field_name="content_type",
+        choices=[
+            ("service", "Service"),
+            ("project", "Project"),
+            ("site", "Site"),
+        ],
+        method=filter_content_type,
+        help_text="Filter by content type model name. Example: content_type=service",
+    )
+
+
+class ExporterFilter(django_filters.rest_framework.FilterSet):
+    project = django_filters.CharFilter(
+        field_name="project__name",
+        lookup_expr="contains",
+        help_text="Filter by project name containing a specific substring. "
+        "Example: project=Example Project",
+    )
+    job = django_filters.CharFilter(
+        field_name="job",
+        lookup_expr="contains",
+        help_text="Filter by job name containing a specific substring. Example: job=prometheus",
+    )
+    path = django_filters.CharFilter(
+        field_name="path",
+        lookup_expr="contains",
+        help_text="Filter by path containing a specific substring. Example: path=/metrics",
+    )
+    scheme = django_filters.ChoiceFilter(
+        field_name="scheme",
+        choices=[
+            ("http", "HTTP"),
+            ("https", "HTTPS"),
+        ],
+        lookup_expr="exact",
+        help_text="Filter by exact scheme. Example: scheme=http",
+    )
+    enabled = django_filters.BooleanFilter(
+        field_name="enabled",
+        help_text="Filter by enabled status (true or false). Example: enabled=true",
+    )
+
+
+class URLFilter(django_filters.rest_framework.FilterSet):
+    project = django_filters.CharFilter(
+        field_name="project__name",
+        lookup_expr="contains",
+        help_text="Filter by project name containing a specific substring. "
+        "Example: project=Example Project",
+    )
+    probe = django_filters.ChoiceFilter(
+        field_name="probe__module",
+        choices=models.Probe.objects.values_list("module", "description").distinct(),
+        help_text="Filter by exact probe scheme. Example: probe=http_2xx",
+    )
+
+
+class GroupFilter(django_filters.rest_framework.FilterSet):
+    name = django_filters.CharFilter(
+        field_name="name",
+        lookup_expr="contains",
+        help_text="Filter by group name containing a specific substring. "
+        "Example: name=Example Group",
+    )
+
+
+class ProjectFilterV2(django_filters.rest_framework.FilterSet):
+    name = django_filters.CharFilter(
+        field_name="name",
+        lookup_expr="contains",
+        help_text="Filter by project name containing a specific substring. "
+        "Example: name=Example Project",
+    )
+    service = django_filters.CharFilter(
+        field_name="service__name",
+        lookup_expr="exact",
+        help_text="Filter by exact service name. Example: service=Example Service",
+    )
+    shard = django_filters.CharFilter(
+        field_name="shard__name",
+        lookup_expr="exact",
+        help_text="Filter by exact shard name. Example: shard=Example Shard",
+    )
+    owner = django_filters.CharFilter(
+        field_name="owner__username",
+        lookup_expr="exact",
+        help_text="Filter by exact owner username. Example: owner=Example Owner",
+    )
+
+
+class ServiceFilterV2(django_filters.rest_framework.FilterSet):
+    name = django_filters.CharFilter(
+        field_name="name",
+        lookup_expr="contains",
+        help_text="Filter by service name containing a specific substring. "
+        "Example: name=Example Service",
+    )
+    owner = django_filters.CharFilter(
+        field_name="owner__username",
+        lookup_expr="exact",
+        help_text="Filter by exact owner username. Example: owner=Example Owner",
+    )
+
+
+class UserFilter(django_filters.rest_framework.FilterSet):
+    username = django_filters.CharFilter(
+        field_name="username",
+        lookup_expr="contains",
+        help_text="Filter by username containing a specific substring. "
+        "Example: username=Example Username",
+    )
+    email = django_filters.CharFilter(
+        field_name="email",
+        lookup_expr="contains",
+        help_text="Filter by email containing a specific substring. "
+        "Example: email=example@example.com",
+    )