Django REST Framework API rules

# AGENTS.md: Django REST Framework API

Django project serving a JSON API with Django REST Framework (DRF). Check `pyproject.toml` or `uv.lock` for the Django
and DRF versions before using newer APIs.

## Commands
- Tests: `uv run python manage.py test` (or `uv run pytest` if pytest-django is set up).
- Checks: `uv run python manage.py check` and `uv run python manage.py makemigrations --check --dry-run`.
- Done means: tests green, no missing migrations, every new endpoint covered by the tests listed below.

## Security defaults
- `DEFAULT_PERMISSION_CLASSES` is `IsAuthenticated`. Never add `AllowAny` to an endpoint without the user asking.
- Scope data in `get_queryset()` to the requesting user or tenant: `Note.objects.filter(owner=self.request.user)`.
  Another user's object is then a 404, not a 403 that confirms it exists.
- Set ownership on the server: `perform_create(self, serializer): serializer.save(owner=self.request.user)`. Never
  trust an owner or tenant field from the request body.
- Throttle anonymous and costly endpoints (`DEFAULT_THROTTLE_CLASSES` or per-view `throttle_classes`).

## Serializers
- List `fields` explicitly. Never `fields = "__all__"` or `exclude`: a new column must not leak into the API.
- Mark server-set fields `read_only_fields`. Validate in `validate_<field>` or `validate()`, not in views.
- Nested writes only when asked; prefer separate endpoints.

## Views and queries
- `ModelViewSet` or generic views with a router; keep views thin.
- Paginate every list endpoint (`DEFAULT_PAGINATION_CLASS`).
- `select_related` / `prefetch_related` in `get_queryset()` for every relation the serializer reads. Prove it with
  `assertNumQueries` in a test.

## Tests for every endpoint
- Anonymous request rejected; owner can do the action; lists show only the user's rows; another user gets 404;
  invalid input returns 400 naming the field; list query count stays flat as rows grow. Use the `drf-endpoint` skill.
- `APITestCase` with `force_authenticate`. Test passwords and data are obviously fake.

## Secrets and settings
- `SECRET_KEY`, database URLs and API keys come from the environment. `DEBUG` defaults to off.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `drf-endpoint`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Django REST Framework API rules" v1.0.0 — https://loadout.jnw-it.com/loadouts/django-rest-api/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `drf-endpoint`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Django REST Framework API rules" v1.0.0 — https://loadout.jnw-it.com/loadouts/django-rest-api/ -->

---
name: drf-endpoint
description: Add a Django REST Framework endpoint with an explicit serializer, a user-scoped queryset, server-set ownership, pagination and the six tests every endpoint needs.
---

# Add a DRF endpoint

Examples: `references/serializers.py`, `references/views.py`, `references/urls.py`, `references/tests.py`.

1. Model first, if needed: add it, then `uv run python manage.py makemigrations` and check the migration.
2. Serializer: explicit `fields`, server-set fields in `read_only_fields`, validation in `validate_<field>`.
3. View: `ModelViewSet` (or a narrower generic view) with:
   - `get_queryset()` filtered to `self.request.user`, with `select_related` for relations the serializer reads
   - `perform_create()` that sets the owner
   - permissions no weaker than the project default
4. Route it with a `DefaultRouter` and `basename`.
5. Tests (`APITestCase`):
   - anonymous is rejected (401 or 403, depending on the authentication class)
   - create sets the owner from the request, ignoring an owner in the body
   - list shows only the user's own rows
   - another user's object is 404 for read, update and delete
   - invalid input is a 400 that names the field
   - `assertNumQueries` on the list endpoint with several rows
6. Run `uv run python manage.py test`, `check` and `makemigrations --check --dry-run`.

from rest_framework import serializers

from notes.models import Note


class NoteSerializer(serializers.ModelSerializer):
    # Explicit fields: a new model column never leaks into the API by accident.
    owner = serializers.CharField(source="owner.username", read_only=True)

    class Meta:
        model = Note
        fields = ["id", "title", "body", "owner", "created_at"]
        read_only_fields = ["id", "owner", "created_at"]

    def validate_title(self, value: str) -> str:
        value = value.strip()
        if len(value) < 3:
            raise serializers.ValidationError("Title must be at least 3 characters.")
        return value

from rest_framework import permissions, viewsets

from notes.models import Note
from notes.serializers import NoteSerializer


class NoteViewSet(viewsets.ModelViewSet):
    """Notes belong to one user. Every query is scoped to request.user, so other users' notes are a 404."""

    serializer_class = NoteSerializer
    permission_classes = [permissions.IsAuthenticated]

    def get_queryset(self):
        return Note.objects.filter(owner=self.request.user).select_related("owner").order_by("-created_at", "-id")

    def perform_create(self, serializer):
        serializer.save(owner=self.request.user)

from rest_framework.routers import DefaultRouter

from notes.views import NoteViewSet

router = DefaultRouter()
router.register("notes", NoteViewSet, basename="note")

urlpatterns = router.urls

from django.contrib.auth import get_user_model
from rest_framework import status
from rest_framework.test import APITestCase

from notes.models import Note

User = get_user_model()


class NoteApiTests(APITestCase):
    def setUp(self):
        self.ada = User.objects.create_user("ada", password="test-only-pass")
        self.bob = User.objects.create_user("bob", password="test-only-pass")
        self.bobs_note = Note.objects.create(owner=self.bob, title="Bob's plan", body="private")

    def test_anonymous_requests_are_rejected(self):
        response = self.client.get("/api/notes/")
        self.assertIn(response.status_code, {status.HTTP_401_UNAUTHORIZED, status.HTTP_403_FORBIDDEN})

    def test_create_sets_owner_from_the_request_not_the_body(self):
        self.client.force_authenticate(self.ada)
        response = self.client.post("/api/notes/", {"title": "  Shopping ", "body": "milk", "owner": "bob"})
        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
        self.assertEqual(response.data["owner"], "ada")
        self.assertEqual(response.data["title"], "Shopping")

    def test_list_only_shows_own_notes(self):
        Note.objects.create(owner=self.ada, title="Ada's note", body="")
        self.client.force_authenticate(self.ada)
        response = self.client.get("/api/notes/")
        self.assertEqual(response.status_code, status.HTTP_200_OK)
        self.assertEqual([n["title"] for n in response.data["results"]], ["Ada's note"])

    def test_other_users_note_is_not_found(self):
        self.client.force_authenticate(self.ada)
        for method in ("get", "patch", "delete"):
            response = getattr(self.client, method)(f"/api/notes/{self.bobs_note.pk}/")
            self.assertEqual(response.status_code, status.HTTP_404_NOT_FOUND, method)
        self.assertTrue(Note.objects.filter(pk=self.bobs_note.pk).exists())

    def test_validation_errors_name_the_field(self):
        self.client.force_authenticate(self.ada)
        response = self.client.post("/api/notes/", {"title": "x", "body": ""})
        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
        self.assertIn("title", response.data)

    def test_list_query_count_does_not_grow_with_rows(self):
        for i in range(5):
            Note.objects.create(owner=self.ada, title=f"Note {i}", body="")
        self.client.force_authenticate(self.ada)
        # One count query for pagination, one select with the owner joined.
        with self.assertNumQueries(2):
            self.client.get("/api/notes/")