django-api-utility 0.1.0__py3-none-any.whl

django_api_utility/__init__.py

@@ -0,0 +1,68 @@
+"""Reusable API integration utility for Django services."""
+
+from .exceptions import (
+    ApiUtilityError,
+    ConfigurationError,
+    DefinitionKeyError,
+    EndpointConfigError,
+    EndpointRequestError,
+    HttpClientError,
+    TokenConfigError,
+    TokenRequestError,
+    SchemaValidationError,
+)
+
+
+def request_by_key(*args, **kwargs):
+    from .orchestration.api_service import request_by_key as _request_by_key
+
+    return _request_by_key(*args, **kwargs)
+
+
+def get_by_key(*args, **kwargs):
+    from .orchestration.api_service import get_by_key as _get_by_key
+
+    return _get_by_key(*args, **kwargs)
+
+
+def post_by_key(*args, **kwargs):
+    from .orchestration.api_service import post_by_key as _post_by_key
+
+    return _post_by_key(*args, **kwargs)
+
+
+def put_by_key(*args, **kwargs):
+    from .orchestration.api_service import put_by_key as _put_by_key
+
+    return _put_by_key(*args, **kwargs)
+
+
+def patch_by_key(*args, **kwargs):
+    from .orchestration.api_service import patch_by_key as _patch_by_key
+
+    return _patch_by_key(*args, **kwargs)
+
+
+def delete_by_key(*args, **kwargs):
+    from .orchestration.api_service import delete_by_key as _delete_by_key
+
+    return _delete_by_key(*args, **kwargs)
+
+
+__all__ = [
+    "ApiUtilityError",
+    "ConfigurationError",
+    "DefinitionKeyError",
+    "EndpointConfigError",
+    "EndpointRequestError",
+    "HttpClientError",
+    "TokenConfigError",
+    "TokenRequestError",
+    "SchemaValidationError",
+    "request_by_key",
+    "get_by_key",
+    "post_by_key",
+    "put_by_key",
+    "patch_by_key",
+    "delete_by_key",
+]

django_api_utility/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class DjangoApiUtilityConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_api_utility"
+    verbose_name = "Django API Utility"

django_api_utility/domain/__init__.py

@@ -0,0 +1,15 @@
+"""Domain layer: config lookup, endpoint resolution, and token flow."""
+
+from .definition_keys import clear_definition_key_cache, get_definition_key
+from .endpoint_service import build_url, resolve_endpoint
+from .token_service import get_or_refresh_service_token
+from .types import ResolvedEndpoint
+
+__all__ = [
+    "get_definition_key",
+    "clear_definition_key_cache",
+    "build_url",
+    "resolve_endpoint",
+    "get_or_refresh_service_token",
+    "ResolvedEndpoint",
+]

django_api_utility/domain/definition_keys.py

@@ -0,0 +1,53 @@
+import json
+import os
+from functools import lru_cache
+from pathlib import Path
+
+from django.conf import settings
+
+from django_api_utility.exceptions import DefinitionKeyError
+
+
+_DEFAULT_KEYS_FILE = Path(__file__).resolve().parents[2] / "config" / "external_definition_keys.json"
+
+
+def _keys_file_path() -> Path:
+    configured = (
+        getattr(settings, "EXTERNAL_DEFINITION_KEYS_FILE", "")
+        or os.getenv("EXTERNAL_DEFINITION_KEYS_FILE", "")
+        or str(_DEFAULT_KEYS_FILE)
+    )
+    return Path(configured)
+
+
+@lru_cache(maxsize=1)
+def _load_keys() -> dict:
+    keys_file = _keys_file_path()
+    if not keys_file.exists():
+        raise DefinitionKeyError(
+            f"Definition key config file not found at {keys_file}. "
+            "Set EXTERNAL_DEFINITION_KEYS_FILE to a valid JSON file."
+        )
+
+    try:
+        with keys_file.open("r", encoding="utf-8") as file_obj:
+            data = json.load(file_obj) or {}
+    except json.JSONDecodeError as exc:
+        raise DefinitionKeyError(f"Definition key file is invalid JSON at {keys_file}: {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise DefinitionKeyError("external_definition_keys.json must contain a JSON object")
+    return data
+
+
+def get_definition_key(name: str) -> str:
+    """Resolve runtime key alias to configured endpoint definition key."""
+    keys = _load_keys()
+    value = keys.get(name)
+    if not value:
+        raise DefinitionKeyError(f"Definition key '{name}' not found in {_keys_file_path()}")
+    return str(value)
+
+
+def clear_definition_key_cache() -> None:
+    _load_keys.cache_clear()

django_api_utility/domain/endpoint_service.py

@@ -0,0 +1,34 @@
+from django_api_utility.exceptions import EndpointConfigError
+from django_api_utility.models import ExternalServiceEndpoint
+
+from .token_service import get_or_refresh_service_token
+from .types import ResolvedEndpoint
+
+
+def build_url(base_url: str, path: str) -> str:
+    """Join base URL and endpoint path with normalized slashes."""
+    return f"{base_url.rstrip('/')}/{path.lstrip('/')}"
+
+
+def resolve_endpoint(definition_key: str, force_token_refresh: bool = False) -> ResolvedEndpoint:
+    """Resolve active endpoint config and authorization headers for execution."""
+    endpoint = (
+        ExternalServiceEndpoint.objects.select_related("service")
+        .filter(definition_key=definition_key, is_active=True, service__is_active=True)
+        .first()
+    )
+    if not endpoint:
+        raise EndpointConfigError(f"Active endpoint definition_key '{definition_key}' is not configured")
+
+    headers: dict[str, str] = {}
+    if endpoint.service.auth_required:
+        token = get_or_refresh_service_token(endpoint.service, force_refresh=force_token_refresh)
+        headers["Authorization"] = f"Bearer {token}"
+
+    timeout = endpoint.timeout_seconds or endpoint.service.default_timeout_seconds or 10
+    return ResolvedEndpoint(
+        endpoint=endpoint,
+        url=build_url(endpoint.service.base_url, endpoint.path),
+        timeout=timeout,
+        headers=headers,
+    )

django_api_utility/domain/schema_service.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from django.conf import settings
+
+from django_api_utility.exceptions import SchemaValidationError
+from django_api_utility.models import ExternalEndpointSchema
+
+try:
+    from jsonschema import ValidationError as JsonSchemaValidationError
+    from jsonschema import validate as jsonschema_validate
+except Exception:  # pragma: no cover - import failure path
+    JsonSchemaValidationError = Exception
+    jsonschema_validate = None
+
+
+def schema_validation_enabled() -> bool:
+    return bool(getattr(settings, "API_UTILITY_VALIDATE_SCHEMAS", True))
+
+
+def _get_active_schema(endpoint, schema_kind: str) -> Optional[ExternalEndpointSchema]:
+    # Supports tests that pass mocked/non-model endpoints.
+    endpoint_pk = getattr(endpoint, "pk", None)
+    if not endpoint_pk:
+        return None
+
+    return (
+        ExternalEndpointSchema.objects.filter(
+            endpoint=endpoint,
+            schema_kind=schema_kind,
+            is_active=True,
+        )
+        .order_by("-updated_at")
+        .first()
+    )
+
+
+def validate_payload_schema(*, definition_key: str, endpoint, schema_kind: str, payload: Any) -> None:
+    if not schema_validation_enabled():
+        return
+
+    schema_row = _get_active_schema(endpoint, schema_kind)
+    if not schema_row:
+        return
+
+    if jsonschema_validate is None:
+        raise SchemaValidationError(
+            f"Schema validation requested for '{definition_key}' but jsonschema dependency is unavailable"
+        )
+
+    schema_json = schema_row.schema_json or {}
+    try:
+        jsonschema_validate(instance=payload, schema=schema_json)
+    except JsonSchemaValidationError as exc:
+        raise SchemaValidationError(
+            f"{schema_kind.title()} schema validation failed for '{definition_key}': {exc.message}"
+        ) from exc

django_api_utility/domain/token_service.py

@@ -0,0 +1,125 @@
+from datetime import timedelta
+
+from django.conf import settings
+from django.utils import timezone
+
+from django_api_utility.exceptions import HttpClientError, TokenConfigError, TokenRequestError
+from django_api_utility.models import ExternalServiceEndpoint, IntegrationServiceTokenConfig
+from django_api_utility.transport.outbound_service import execute_outbound_request
+
+
+def _get_token_config_for_service(service):
+    return (
+        IntegrationServiceTokenConfig.objects.filter(service=service, is_active=True)
+        .order_by("-updated_at")
+        .first()
+    )
+
+
+def _resolve_token_url(service) -> str:
+    configured_key = str(getattr(settings, "API_UTILITY_TOKEN_DEFINITION_KEY", "request_service_token") or "").strip()
+    if not configured_key:
+        configured_key = "request_service_token"
+
+    service_key = str(service.name or "").strip().lower().replace(" ", "_")
+    candidate_keys = [
+        configured_key,
+        "request_service_token",
+        "request_token",
+        f"{service_key}_{configured_key}",
+        f"{service_key}_request_service_token",
+        f"{service_key}_request_token",
+    ]
+
+    token_endpoint = None
+    for key in candidate_keys:
+        token_endpoint = (
+            ExternalServiceEndpoint.objects.filter(
+                service=service,
+                is_active=True,
+                method__iexact="POST",
+                definition_key__iexact=key,
+            )
+            .order_by("id")
+            .first()
+        )
+        if token_endpoint:
+            break
+
+    if not token_endpoint:
+        raise TokenConfigError(
+            f"Token endpoint not configured in ExternalServiceEndpoint for service '{service.name}'. "
+            f"Expected definition_key one of: {candidate_keys}"
+        )
+
+    return f"{service.base_url.rstrip('/')}/{token_endpoint.path.lstrip('/')}"
+
+
+def _request_new_service_token(config, service) -> str:
+    token_service = config.service or service
+    if config.service_id and config.service_id != service.id:
+        raise TokenConfigError(
+            f"Token config service mismatch. Config is for '{config.service.name}', "
+            f"requested service is '{service.name}'."
+        )
+
+    token_url = _resolve_token_url(token_service)
+    grant_type = str(getattr(settings, "API_UTILITY_TOKEN_GRANT_TYPE", "client_credentials") or "client_credentials")
+    scope = str(getattr(settings, "API_UTILITY_TOKEN_SCOPE", "") or "").strip()
+
+    payload = {
+        "grant_type": grant_type,
+        "client_id": config.client_id,
+        "client_secret": config.get_client_secret(),
+    }
+    if scope:
+        payload["scope"] = scope
+
+    timeout = int(getattr(settings, "API_UTILITY_TOKEN_TIMEOUT_SECONDS", 10) or 10)
+    try:
+        response = execute_outbound_request(
+            method="POST",
+            url=token_url,
+            form_data=payload,
+            timeout=timeout,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+    except HttpClientError as exc:
+        raise TokenRequestError(f"Token request failed for service '{token_service.name}': {exc}") from exc
+
+    if response.status_code >= 400:
+        raise TokenRequestError(
+            f"Token request failed for service '{token_service.name}' "
+            f"with status {response.status_code}: {response.text[:500]}"
+        )
+
+    try:
+        body = response.json() or {}
+    except ValueError as exc:
+        raise TokenRequestError(f"Token response for service '{token_service.name}' is not valid JSON") from exc
+
+    access_token = str(body.get("access_token") or "").strip()
+    if not access_token:
+        raise TokenRequestError(f"Token response for service '{token_service.name}' missing access_token")
+
+    expires_in = int(body.get("expires_in") or getattr(settings, "API_UTILITY_DEFAULT_TOKEN_EXPIRES_IN", 3600))
+    config.set_service_token(access_token)
+    config.token_expiry = timezone.now() + timedelta(seconds=max(expires_in, 1))
+    config.save(update_fields=["service_token", "token_expiry", "updated_at"])
+    return access_token
+
+
+def get_or_refresh_service_token(service, force_refresh: bool = False) -> str:
+    """Return valid token for service and refresh it when required."""
+    config = _get_token_config_for_service(service)
+    if not config:
+        raise TokenConfigError(
+            f"No active IntegrationServiceTokenConfig found for service '{service.name}'. "
+            "Save token config with matching service first."
+        )
+
+    buffer_seconds = int(getattr(settings, "API_UTILITY_TOKEN_EXPIRY_BUFFER_SECONDS", 60) or 60)
+    if not force_refresh and config.has_valid_service_token(buffer_seconds=buffer_seconds):
+        return config.get_service_token()
+
+    return _request_new_service_token(config=config, service=service)

django_api_utility/domain/types.py

@@ -0,0 +1,14 @@
+from dataclasses import dataclass, field
+from typing import Dict
+
+from django_api_utility.models import ExternalServiceEndpoint
+
+
+@dataclass(frozen=True)
+class ResolvedEndpoint:
+    """Resolved endpoint metadata required to execute a request."""
+
+    endpoint: ExternalServiceEndpoint
+    url: str
+    timeout: int
+    headers: Dict[str, str] = field(default_factory=dict)

django_api_utility/exceptions.py

@@ -0,0 +1,34 @@
+class ApiUtilityError(Exception):
+    """Base exception for the utility."""
+
+
+class ConfigurationError(ApiUtilityError):
+    """Raised when static utility configuration is invalid."""
+
+
+class DefinitionKeyError(ConfigurationError):
+    """Raised when a definition key cannot be loaded/resolved."""
+
+
+class EndpointConfigError(ConfigurationError):
+    """Raised when endpoint config is missing or invalid."""
+
+
+class TokenConfigError(ConfigurationError):
+    """Raised when token config is missing or invalid."""
+
+
+class HttpClientError(ApiUtilityError):
+    """Raised when an outbound HTTP call fails at transport layer."""
+
+
+class TokenRequestError(ApiUtilityError):
+    """Raised when token endpoint request/response is invalid."""
+
+
+class EndpointRequestError(ApiUtilityError):
+    """Raised when endpoint request execution fails."""
+
+
+class SchemaValidationError(EndpointRequestError):
+    """Raised when request/response schema validation fails."""

django_api_utility/migrations/0001_initial.py

@@ -0,0 +1,110 @@
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="ExternalServiceConfig",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
+                ("name", models.CharField(max_length=100, unique=True)),
+                ("base_url", models.CharField(max_length=500)),
+                ("default_timeout_seconds", models.PositiveIntegerField(default=10)),
+                ("auth_required", models.BooleanField(default=True)),
+                ("is_active", models.BooleanField(default=True)),
+                ("description", models.TextField(blank=True, default="")),
+            ],
+            options={
+                "ordering": ["name"],
+            },
+        ),
+        migrations.CreateModel(
+            name="ExternalServiceEndpoint",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
+                (
+                    "service",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="endpoints",
+                        to="django_api_utility.externalserviceconfig",
+                    ),
+                ),
+                ("definition_key", models.CharField(db_index=True, max_length=150, unique=True)),
+                ("path", models.CharField(max_length=500)),
+                ("method", models.CharField(default="GET", max_length=10)),
+                ("timeout_seconds", models.PositiveIntegerField(blank=True, null=True)),
+                ("is_active", models.BooleanField(default=True)),
+                ("description", models.TextField(blank=True, default="")),
+            ],
+            options={
+                "ordering": ["service__name", "definition_key"],
+            },
+        ),
+        migrations.CreateModel(
+            name="IntegrationServiceTokenConfig",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
+                ("key", models.CharField(db_index=True, max_length=120, unique=True)),
+                (
+                    "service",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        related_name="token_configs",
+                        to="django_api_utility.externalserviceconfig",
+                    ),
+                ),
+                ("client_id", models.CharField(max_length=200)),
+                ("client_secret", models.CharField(max_length=255)),
+                ("service_token", models.TextField(blank=True, default="")),
+                ("token_expiry", models.DateTimeField(blank=True, null=True)),
+                ("is_active", models.BooleanField(default=True)),
+                ("description", models.TextField(blank=True, default="")),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+            ],
+            options={
+                "ordering": ["key"],
+            },
+        ),
+        migrations.CreateModel(
+            name="ExternalEndpointSchema",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
+                (
+                    "endpoint",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="schemas",
+                        to="django_api_utility.externalserviceendpoint",
+                    ),
+                ),
+                (
+                    "schema_kind",
+                    models.CharField(
+                        choices=[("request", "Request"), ("response", "Response")],
+                        max_length=20,
+                    ),
+                ),
+                ("schema_version", models.CharField(default="v1", max_length=40)),
+                ("schema_json", models.JSONField(blank=True, default=dict)),
+                ("sample_payload", models.JSONField(blank=True, default=dict)),
+                ("is_active", models.BooleanField(default=True)),
+                ("description", models.TextField(blank=True, default="")),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+            ],
+            options={
+                "ordering": ["endpoint__definition_key", "schema_kind", "-updated_at"],
+                "unique_together": {("endpoint", "schema_kind", "schema_version")},
+            },
+        ),
+    ]
+

django_api_utility/migrations/__init__.py

@@ -0,0 +1 @@
+

django_api_utility/models.py

@@ -0,0 +1,142 @@
+import base64
+import hashlib
+from datetime import timedelta
+
+from cryptography.fernet import Fernet, InvalidToken
+from django.db import models
+from django.conf import settings
+from django.utils import timezone
+
+
+class ExternalServiceConfig(models.Model):
+    name = models.CharField(max_length=100, unique=True)
+    base_url = models.CharField(max_length=500)
+    default_timeout_seconds = models.PositiveIntegerField(default=10)
+    auth_required = models.BooleanField(default=True)
+    is_active = models.BooleanField(default=True)
+    description = models.TextField(blank=True, default="")
+
+    class Meta:
+        ordering = ["name"]
+
+    def __str__(self):
+        return self.name
+
+
+class ExternalServiceEndpoint(models.Model):
+    service = models.ForeignKey(
+        ExternalServiceConfig,
+        on_delete=models.CASCADE,
+        related_name="endpoints",
+    )
+    definition_key = models.CharField(max_length=150, unique=True, db_index=True)
+    path = models.CharField(max_length=500)
+    method = models.CharField(max_length=10, default="GET")
+    timeout_seconds = models.PositiveIntegerField(null=True, blank=True)
+    is_active = models.BooleanField(default=True)
+    description = models.TextField(blank=True, default="")
+
+    class Meta:
+        ordering = ["service__name", "definition_key"]
+
+    def __str__(self):
+        return f"{self.definition_key} ({self.service.name})"
+
+
+class ExternalEndpointSchema(models.Model):
+    SCHEMA_KIND_CHOICES = (
+        ("request", "Request"),
+        ("response", "Response"),
+    )
+
+    endpoint = models.ForeignKey(
+        ExternalServiceEndpoint,
+        on_delete=models.CASCADE,
+        related_name="schemas",
+    )
+    schema_kind = models.CharField(max_length=20, choices=SCHEMA_KIND_CHOICES)
+    schema_version = models.CharField(max_length=40, default="v1")
+    schema_json = models.JSONField(default=dict, blank=True)
+    sample_payload = models.JSONField(default=dict, blank=True)
+    is_active = models.BooleanField(default=True)
+    description = models.TextField(blank=True, default="")
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        ordering = ["endpoint__definition_key", "schema_kind", "-updated_at"]
+        unique_together = ("endpoint", "schema_kind", "schema_version")
+
+    def __str__(self):
+        return f"{self.endpoint.definition_key}:{self.schema_kind}:{self.schema_version}"
+
+
+def _get_fernet() -> Fernet:
+    key = getattr(settings, "API_UTILITY_FERNET_KEY", None)
+    if key:
+        raw_key = str(key).encode("utf-8")
+    else:
+        digest = hashlib.sha256(str(settings.SECRET_KEY).encode("utf-8")).digest()
+        raw_key = base64.urlsafe_b64encode(digest)
+    return Fernet(raw_key)
+
+
+class IntegrationServiceTokenConfig(models.Model):
+    key = models.CharField(max_length=120, unique=True, db_index=True)
+    service = models.ForeignKey(
+        "django_api_utility.ExternalServiceConfig",
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="token_configs",
+    )
+    client_id = models.CharField(max_length=200)
+    client_secret = models.CharField(max_length=255)
+    service_token = models.TextField(blank=True, default="")
+    token_expiry = models.DateTimeField(null=True, blank=True)
+
+    is_active = models.BooleanField(default=True)
+    description = models.TextField(blank=True, default="")
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        ordering = ["key"]
+
+    def __str__(self):
+        return self.key
+
+    def set_client_secret(self, raw_secret: str):
+        if not raw_secret:
+            self.client_secret = ""
+            return
+        self.client_secret = _get_fernet().encrypt(raw_secret.encode("utf-8")).decode("utf-8")
+
+    def get_client_secret(self) -> str:
+        if not self.client_secret:
+            return ""
+        try:
+            return _get_fernet().decrypt(self.client_secret.encode("utf-8")).decode("utf-8")
+        except (InvalidToken, ValueError, TypeError):
+            # Backward compatibility: allow legacy plaintext value.
+            return self.client_secret
+
+    def set_service_token(self, raw_token: str):
+        if not raw_token:
+            self.service_token = ""
+            return
+        self.service_token = _get_fernet().encrypt(raw_token.encode("utf-8")).decode("utf-8")
+
+    def get_service_token(self) -> str:
+        if not self.service_token:
+            return ""
+        try:
+            return _get_fernet().decrypt(self.service_token.encode("utf-8")).decode("utf-8")
+        except (InvalidToken, ValueError, TypeError):
+            # Backward compatibility: allow legacy plaintext value.
+            return self.service_token
+
+    def has_valid_service_token(self, buffer_seconds: int = 60) -> bool:
+        if not self.service_token or not self.token_expiry:
+            return False
+        return self.token_expiry > timezone.now() + timedelta(seconds=max(int(buffer_seconds), 0))

django_api_utility/orchestration/__init__.py

@@ -0,0 +1,12 @@
+"""Orchestration layer: high-level API request flows."""
+
+from .api_service import delete_by_key, get_by_key, patch_by_key, post_by_key, put_by_key, request_by_key
+
+__all__ = [
+    "request_by_key",
+    "get_by_key",
+    "post_by_key",
+    "put_by_key",
+    "patch_by_key",
+    "delete_by_key",
+]