feat: django-rest-framework + Person/Email API (ietf-tools#8256)

* feat: django-rest-framework + Person/Email API (ietf-tools#8233)

* chore: djangorestframework -> requirements.txt

* chore: auth/perm/schema classes for drf

* chore: settings for drf and friends

* chore: comment that api/serializer.py is not DRF

* feat: URL router for DRF

* feat: simple api/v3/person/{id} endpoint

* fix: actually working demo endpoint

* chore: no auth for PersonViewSet

* ci: params in ci-run-tests.yml

* Revert "ci: params in ci-run-tests.yml"

This reverts commit 03808dd.

* feat: email addresses for person API

* feat: email update api (WIP)

* fix: working Email API endpoint

* chore: annotate address format in api schema

* chore: api adjustments

* feat: expose SpectacularAPIView

At least for now...

* chore: better schema_path_prefix

* feat: permissions for DRF API

* refactor: use permissions classes

* refactor: extract NewEmailForm validation for reuse

* refactor: ietfauth.validators module

* refactor: send new email conf req via helper

* feat: API call to issue new address request

* chore: move datatracker DRF api to /api/core/

* fix: unused import

* fix: lint

* test: drf URL names + API tests (ietf-tools#8248)

* refactor: better drf URL naming

* test: test person-detail view

* test: permissions

* test: add_email tests + stubs

* test: test email update

* test: test 404 vs 403

* fix: fix permissions

* test: test email partial update

* test: assert we have a nonexistent PK

* chore: disable DRF api for now

* chore: fix git inanity

* fix: lint

* test: disable tests of disabled code

* test: more lint

Author: jennifer-richards

ietf/api/apps.py

@@ -12,4 +12,8 @@ def ready(self):
         interact with the database. See        
         https://docs.djangoproject.com/en/4.2/ref/applications/#django.apps.AppConfig.ready
         """
+        # Populate our API list now that the app registry is set up
         populate_api_list()
+
+        # Import drf-spectacular extensions 
+        import ietf.api.schema  # pyflakes: ignore

ietf/api/authentication.py

@@ -0,0 +1,19 @@
+# Copyright The IETF Trust 2024, All Rights Reserved
+#
+from rest_framework import authentication
+from django.contrib.auth.models import AnonymousUser
+
+
+class ApiKeyAuthentication(authentication.BaseAuthentication):
+    """API-Key header authentication"""
+
+    def authenticate(self, request):
+        """Extract the authentication token, if present
+        
+        This does not validate the token, it just arranges for it to be available in request.auth.
+        It's up to a Permissions class to validate it for the appropriate endpoint.
+        """
+        token = request.META.get("HTTP_X_API_KEY", None)
+        if token is None:
+            return None
+        return AnonymousUser(), token  # available as request.user and request.auth

ietf/api/permissions.py

@@ -0,0 +1,39 @@
+# Copyright The IETF Trust 2024, All Rights Reserved
+#
+from rest_framework import permissions
+from ietf.api.ietf_utils import is_valid_token
+
+
+class HasApiKey(permissions.BasePermission):
+    """Permissions class that validates a token using is_valid_token
+    
+    The view class must indicate the relevant endpoint by setting `api_key_endpoint`.
+    Must be used with an Authentication class that puts a token in request.auth.
+    """
+    def has_permission(self, request, view):
+        endpoint = getattr(view, "api_key_endpoint", None)
+        auth_token = getattr(request, "auth", None)
+        if endpoint is not None and auth_token is not None:
+            return is_valid_token(endpoint, auth_token)
+        return False
+
+
+class IsOwnPerson(permissions.BasePermission):
+    """Permission to access own Person object"""
+    def has_object_permission(self, request, view, obj):
+        if not (request.user.is_authenticated and hasattr(request.user, "person")):
+            return False
+        return obj == request.user.person
+
+
+class BelongsToOwnPerson(permissions.BasePermission):
+    """Permission to access objects associated with own Person
+    
+    Requires that the object have a "person" field that indicates ownership.
+    """
+    def has_object_permission(self, request, view, obj):
+        if not (request.user.is_authenticated and hasattr(request.user, "person")):
+            return False
+        return (
+            hasattr(obj, "person") and obj.person == request.user.person
+        )

ietf/api/routers.py

@@ -0,0 +1,16 @@
+# Copyright The IETF Trust 2024, All Rights Reserved
+"""Custom django-rest-framework routers"""
+from django.core.exceptions import ImproperlyConfigured
+from rest_framework import routers
+
+class PrefixedSimpleRouter(routers.SimpleRouter):
+    """SimpleRouter that adds a dot-separated prefix to its basename"""
+    def __init__(self, name_prefix="", *args, **kwargs):
+        self.name_prefix = name_prefix
+        if len(self.name_prefix) == 0 or self.name_prefix[-1] == ".":
+            raise ImproperlyConfigured("Cannot use a name_prefix that is empty or ends with '.'")
+        super().__init__(*args, **kwargs)
+
+    def get_default_basename(self, viewset):
+        basename = super().get_default_basename(viewset)
+        return f"{self.name_prefix}.{basename}"

ietf/api/schema.py

@@ -0,0 +1,20 @@
+# Copyright The IETF Trust 2024, All Rights Reserved
+#
+from drf_spectacular.extensions import OpenApiAuthenticationExtension
+
+
+class ApiKeyAuthenticationScheme(OpenApiAuthenticationExtension):
+    """Authentication scheme extension for the ApiKeyAuthentication
+
+    Used by drf-spectacular when rendering the OpenAPI schema
+    """
+    target_class = "ietf.api.authentication.ApiKeyAuthentication"
+    name = "apiKeyAuth"
+
+    def get_security_definition(self, auto_schema):
+        return {
+            "type": "apiKey",
+            "description": "Shared secret in the X-Api-Key header",
+            "name": "X-Api-Key",
+            "in": "header",
+        }

ietf/api/serializer.py

@@ -1,6 +1,9 @@
-# Copyright The IETF Trust 2018-2020, All Rights Reserved
+# Copyright The IETF Trust 2018-2024, All Rights Reserved
 # -*- coding: utf-8 -*-
+"""Serialization utilities
 
+This is _not_ for django-rest-framework!
+"""
 
 import hashlib
 import json