Auth locked down who can hit /api/purchases/ and what they can do once they’re there. It never asked the more basic question sitting underneath: what actually comes back when they do?

In our settings.py there’s already an answer, half-given:

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 100,
}

We already have pagination. GET /api/purchases/ doesn’t dump every row in the table — it hands back 100 at a time, with next/previous links doing the rest. It’s easy to not notice this is even happening, which is exactly the problem worth pulling apart: what is PageNumberPagination actually doing to the response, why does it matter now that a Vue table is coming, and — separately — why does the search box sitting right above that Purchases table currently do absolutely nothing?

What PageNumberPagination is actually doing

Before it was added, GET /api/purchases/ returned a bare JSON array — every row, in one response:

[
  { "id": 1, "title": "...", ... },
  { "id": 2, "title": "...", ... }
]

With PageNumberPagination in place, the same endpoint returns something structurally different:

{
  "count": 1000,
  "next": "http://127.0.0.1:8000/api/purchases/?page=2",
  "previous": null,
  "results": [ { "id": 1, "title": "...", ... }, ... ]
}

That’s not a cosmetic change. The array moved — it’s now results, one key among several, sitting alongside count, next, and previous. Any code written against the old shape (response.data[0]) breaks the moment pagination is turned on, because response.data is no longer a list at all — it’s a dict. This is the kind of thing worth naming explicitly, because it’s exactly the shape a Vue component has to .map() over later — response.data.results, not response.data.

PageNumberPagination vs. LimitOffsetPagination

DRF ships two built-in strategies, and they’re not interchangeable — they encode two different mental models of “where am I in this list”:

  • PageNumberPagination thinks in pages: ?page=2 means “the second page of PAGE_SIZE rows,” full stop. You don’t control how many rows are on a page per-request — that’s fixed server-side.
  • LimitOffsetPagination thinks in rows: ?limit=25&offset=50 means “25 rows, starting after the 50th.” The client decides the page size per-request, not just which page.

For a Vue table with Previous/Next buttons and a “showing 51–75 of 1000” row-count display — the kind of UI already planned for this project — offset/limit maps onto that display far more directly: offset is “51,” and offset + limit is “75.” With page numbers, you’d be back-calculating row ranges from a page number and a fixed page size every time you render that text. Worth deciding this now, before the Vue tables are built, rather than retrofitting it later.

Where filtering actually stands right now

Pagination came for free from a two-line settings change. The search box doesn’t — the Vue table already sends ?search=<value> on every keystroke, same as the Countries table:

// frontend/src/views/Purchases.vue
const params = new URLSearchParams({ page: page.value })
if (searchValue.value) {
    params.set('search', searchValue.value)
}

But PurchaseViewSet has no idea that parameter exists:

class PurchaseViewSet(viewsets.ModelViewSet):
    queryset = Purchase.objects.prefetch_related('items')
    serializer_class = PurchaseSerializer

queryset is fixed at class-definition time — it’s just “every Purchase, with its items prefetched.” Nothing here ever looks at request, so nothing here can possibly know what the client asked to narrow down. Right now ?search=Europe is silently ignored — the frontend already built the box, the backend just isn’t listening yet.

(The real class also carries get_permissions() and the refunds action from the permissions post — trimmed from the snippets below to keep the focus on filtering, but they’re still there in every version of this class we actually run.)

Everything from here on is a proposal, not a record of shipped code — none of it is in the repo yet. This is the design discussion for the next change, worked through before touching the actual project. Worth being precise about the shape of that change, too: the Vue table sends one free-text term per request, not a set of separate per-field parameters (no min/max price inputs exist anywhere in the UI) — so the right backend match is DRF’s own SearchFilter, not django-filter. The latter is built for structured, per-field query params like ?min_price=50; it would be solving a problem this UI doesn’t actually have.

Matching the search box, by hand, first

The obvious fix is to override get_queryset() and read the query string ourselves:

from django.db.models import Q

class PurchaseViewSet(viewsets.ModelViewSet):
    serializer_class = PurchaseSerializer

    def get_queryset(self):
        queryset = Purchase.objects.prefetch_related('items')

        search = self.request.query_params.get('search')
        if search:
            queryset = queryset.filter(
                Q(city__icontains=search) |
                Q(country__name__icontains=search) |
                Q(country__continent__icontains=search)
            )

        return queryset

One term, matched against three fields with Q objects OR’d together — country__name and country__continent both cross the same foreign key, Purchase → Country, the same double-underscore syntax needed anywhere this relationship matters. continent specifically isn’t a field on Purchase itself — it only shows up in the serialized response because PurchaseSerializer pulls it off the related Country (source='country.continent'). Filter continent directly against Purchase and Django raises FieldError: Cannot resolve keyword 'continent' into field the moment the queryset is evaluated; it has to be country__continent.

On paper, this is enough: typing “Europe” into the search box would genuinely narrow the Purchases table once it’s actually wired in. But the pattern doesn’t stay this short — add a fourth searchable field (say, the purchased items’ product names) and it’s one more Q(...) OR’d onto a growing chain, one more chance to get the lookup wrong and have it fail silently instead of erroring.

The declarative fix: SearchFilter

Unlike django-filter, this needs no new dependency — SearchFilter ships inside rest_framework.filters, already installed as part of DRF itself. Declare the searchable fields on the viewset and let DRF build the Q-object OR chain for you:

from rest_framework import filters

class PurchaseViewSet(viewsets.ModelViewSet):
    queryset = Purchase.objects.prefetch_related('items')
    serializer_class = PurchaseSerializer
    filter_backends = [filters.SearchFilter]
    search_fields = ['city', 'country__name', 'country__continent']

search_fields is the declared list; country__continent carries over the same relationship-crossing path used in the hand-written version — SearchFilter doesn’t know any more about the Purchase/Country relationship than our own Q objects did, it just builds the same kind of query from a list instead of a method body. Every field defaults to a case-insensitive icontains — the same lookup picked by hand above — and DRF supports prefixing a field name with ^ (starts-with), = (exact), or @ (full-text search, database-dependent) for the cases where icontains isn’t the right match; none of those are needed here. One request param (search), one declared list, no new package — closer to what the UI is actually asking for than a filter class built around separate per-field params would have been.

The Countries table sends the same ?search= shape and would need the identical treatment on CountryViewSet — out of scope here, but worth remembering it’s not automatic just because PurchaseViewSet has it.

Pagination and search, together

Once this is actually wired in, the two combine automatically — no extra code needed. GET /api/purchases/?search=Europe&page=2 would filter first, then paginate what’s left, into something shaped like this:

{
  "count": 42,
  "next": "http://127.0.0.1:8000/api/purchases/?search=Europe&page=3",
  "previous": "http://127.0.0.1:8000/api/purchases/?search=Europe",
  "results": [ { "id": 87, "city": "Berlin", "country_name": "Germany", "continent": "Europe", ... }, ... ]
}

count would reflect the filtered total (42, not 1000) — the next/previous links would even carry the search term forward automatically, so the Vue table’s Next button doesn’t need to remember and reattach whatever was typed into the box. That falls out of SearchFilter and PageNumberPagination both operating on the same queryset in sequence, one narrowing it, the other slicing what’s left — a consequence of how the two pieces are designed to compose, not something that needs separate wiring.