Search & Filtering

ZoneVast services support querying data through URL query parameters. The exact capabilities depend on the framework and the specific endpoint.

Search

Full-Text Search

Use the search parameter to perform a broad text search across relevant fields:

GET /api/v1/project/project/projects/?search=my+project

In Django, this uses SearchFilter which performs case-insensitive icontains lookups across configured fields.

Field-Level Search

For more targeted searches, filter by specific fields:

GET /api/v1/project/project/projects/?username=my-project
GET /api/v1/project/project/account/users/?first_name=john

Filter Syntax

Exact Match

Pass the field name and value directly:

GET /api/v1/project/project/account/users/?sex=male
GET /api/v1/project/project/account/users/?phone_number=+9647500000001

Partial Match (Contains)

Some Django endpoints support icontains via django-filters:

GET /api/v1/project/project/account/users/?first_name=john

This performs a case-insensitive partial match when configured with lookup_expr='icontains'.

Range Filters

Filter within a range of values:

GET /api/v1/project/project/attachment/?created_after=2026-01-01
GET /api/v1/project/project/attachment/?created_before=2026-04-30

Multi-Value (IN)

Some Django endpoints support multi-value filtering:

GET /api/v1/project/project/attachment/?type=image&type=video

File-Specific Filters

The project service's attachment endpoints support:

GET /api/v1/project/project/attachment/?type=image
GET /api/v1/project/project/attachment/?mime_type=image/png
GET /api/v1/project/project/attachment/?min_size=1024
GET /api/v1/project/project/attachment/?max_size=10485760

Sorting

Django — Ordering

Use the ordering parameter with field names. Prefix with - for descending:

GET /api/v1/project/project/projects/?ordering=-created_at     # Newest first
GET /api/v1/project/project/projects/?ordering=title            # A-Z
GET /api/v1/project/project/projects/?ordering=-updated_at,title # Multi-field

NestJS — Sort Parameters

NestJS services typically use sort or sortBy with sortOrder:

GET /api/v1/auctions?sort=created_at&sortOrder=DESC
GET /api/v1/auctions?sort=price&sortOrder=ASC

Combining Parameters

All query parameters can be combined with pagination:

GET /api/v1/project/project/projects/?search=test&ordering=-created_at&page=2&limit=20

This searches for "test", sorts by newest first, and returns page 2 with 20 items per page.

Availability Matrix

Not all endpoints support all filters. The table below shows general support:

|| Capability | Django DRF | NestJS | ||------------|-----------|--------| || Full-text search (?search=) | With SearchFilter | Per-endpoint | || Exact match (?field=value) | With DjangoFilterBackend | Per-endpoint | || Range filters | With custom FilterSet | Per-endpoint | || Ordering (?ordering=) | With OrderingFilter | ?sort= + ?sortOrder= | || Pagination combined | Yes | Yes |

Tip: Check each service's documentation for available filters on specific endpoints. Not all views have filtering enabled.

Client-Side Example

interface QueryOptions {
  search?: string;
  page?: number;
  limit?: number;
  ordering?: string;
  [key: string]: string | number | boolean | undefined;
}

function buildQueryParams(options: QueryOptions): string {
  const params = new URLSearchParams();

  Object.entries(options).forEach(([key, value]) => {
    if (value !== undefined && value !== '') {
      params.append(key, String(value));
    }
  });

  return params.toString();
}

// Usage
const query = buildQueryParams({
  search: 'project',
  ordering: '-created_at',
  page: 1,
  limit: 20,
  status: 'active',
});

const url = `/api/v1/project/project/projects/?${query}`;

What's Next

• Pagination — How paginated results are returned
• API Response Format — Response structure
• Rate Limiting — Request limits and throttling