Filtering & Sorting

The MyWarranties API supports filtering and sorting on list endpoints to help you find specific data.

Query Parameters

Filtering

Parameter	Type	Description	Example
brand	string	Filter by brand	?brand=Apple
category	string	Filter by category	?category=Electronics
status	string	Filter by status	?status=open
search	string	Full-text search	?search=iPhone
date_from	date	From date (YYYY-MM-DD)	?date_from=2024-01-01
date_to	date	To date (YYYY-MM-DD)	?date_to=2024-12-31

Sorting

Parameter	Type	Description	Example
sort	string	Field to sort by	?sort=name
order	string	Sort order: asc or desc	?order=desc

Products Filtering

Available Filters

GET /api/products?brand=Apple&category=Electronics&sort=name&order=asc

Filters:

• brand - Product brand
• category - Product category
• search - Search in name, brand, description
• warranty_status - active, expired, expiring_soon (within 30 days)
• purchase_date_from - Products purchased after date
• purchase_date_to - Products purchased before date

Sort Fields:

• name - Product name
• brand - Brand name
• purchase_date - Purchase date
• warranty_end_date - Warranty expiration
• created_at - Creation date

Examples

Active warranties only:

GET /api/products?warranty_status=active

Apple products expiring soon:

GET /api/products?brand=Apple&warranty_status=expiring_soon

Search for "iPhone":

GET /api/products?search=iPhone

Electronics sorted by warranty expiration:

GET /api/products?category=Electronics&sort=warranty_end_date&order=asc

Claims Filtering

Available Filters

GET /api/claims?status=open&sort=created_at&order=desc

Filters:

• status - open, in_progress, resolved, closed
• product_id - Claims for specific product
• search - Search in description
• created_from - Claims created after date
• created_to - Claims created before date

Sort Fields:

• created_at - Creation date
• updated_at - Last update
• status - Claim status

Examples

Open claims:

GET /api/claims?status=open

Claims for product:

GET /api/claims?product_id=123

Recent claims:

GET /api/claims?sort=created_at&order=desc

Claims from last month:

GET /api/claims?created_from=2024-01-01&created_to=2024-01-31

Supplier Claims

Supplier-Specific Filters

GET /api/claims/assigned?status=in_progress

Additional Filters:

• customer_email - Filter by customer email
• priority - Filter by priority level

Admin Filters

Admin Endpoints

GET /api/admin/products?user_id=123&brand=Apple
GET /api/admin/claims?supplier_id=456&status=open
GET /api/admin/users?role=CUSTOMER&search=john

Additional Filters:

• user_id - Filter by specific user
• supplier_id - Filter by supplier
• reseller_id - Filter by reseller
• role - Filter users by role

Response Format

Filtered results maintain the same pagination structure:

{
  "data": [
    // Filtered items
  ],
  "meta": {
    "current_page": 1,
    "total": 15,  // Total matching filter
    "filters_applied": {
      "brand": "Apple",
      "status": "active"
    }
  }
}

Combining Filters

You can combine multiple filters:

GET /api/products?brand=Apple&category=Electronics&warranty_status=active&sort=warranty_end_date&order=asc&page=1&limit=20

All parameters are combined with AND logic.

Search Functionality

The search parameter performs full-text search:

GET /api/products?search=iPhone 15 Pro

Searches in:

• Product name
• Brand
• Description
• Serial number
• Store name

Search is case-insensitive and supports partial matches.

Client Implementation

TypeScript Example

interface ProductFilters {
  brand?: string;
  category?: string;
  warranty_status?: 'active' | 'expired' | 'expiring_soon';
  search?: string;
  sort?: string;
  order?: 'asc' | 'desc';
  page?: number;
  limit?: number;
}

function buildQueryString(filters: ProductFilters): string {
  const params = new URLSearchParams();

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

  return params.toString();
}

async function fetchProducts(filters: ProductFilters = {}) {
  const query = buildQueryString(filters);
  const url = `https://api.my-warranties.nl/api/products?${query}`;

  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });

  return response.json();
}

// Usage
const products = await fetchProducts({
  brand: 'Apple',
  warranty_status: 'active',
  sort: 'warranty_end_date',
  order: 'asc',
  page: 1,
  limit: 20
});

React Filter Component

function ProductFilters() {
  const [filters, setFilters] = useState({
    brand: '',
    category: '',
    warranty_status: 'all',
    search: '',
    sort: 'name',
    order: 'asc'
  });

  const updateFilter = (key: string, value: string) => {
    setFilters(prev => ({ ...prev, [key]: value }));
  };

  return (
    <div>
      <input
        placeholder="Search..."
        value={filters.search}
        onChange={(e) => updateFilter('search', e.target.value)}
      />

      <select
        value={filters.brand}
        onChange={(e) => updateFilter('brand', e.target.value)}
      >
        <option value="">All Brands</option>
        <option value="Apple">Apple</option>
        <option value="Samsung">Samsung</option>
      </select>

      <select
        value={filters.warranty_status}
        onChange={(e) => updateFilter('warranty_status', e.target.value)}
      >
        <option value="all">All Status</option>
        <option value="active">Active</option>
        <option value="expired">Expired</option>
        <option value="expiring_soon">Expiring Soon</option>
      </select>

      <select
        value={filters.sort}
        onChange={(e) => updateFilter('sort', e.target.value)}
      >
        <option value="name">Name</option>
        <option value="brand">Brand</option>
        <option value="warranty_end_date">Warranty End</option>
      </select>

      <button onClick={() => fetchProducts(filters)}>
        Apply Filters
      </button>
    </div>
  );
}

Performance

Database Indexes

All filterable fields are indexed for optimal performance:

• products.brand
• products.category
• products.warranty_end_date
• claims.status
• users.role

Query Optimization

• Filters applied at database level (not in application)
• Efficient use of indexes
• Query results cached for 5 minutes

Recommendations

1. Use specific filters instead of broad searches
2. Limit search term length for better performance
3. Combine filters to narrow results
4. Use pagination with filters
5. Cache filter results on client side

Validation

Invalid Filter Values

{
  "error": "ValidationError",
  "message": "Invalid warranty_status value",
  "code": "VALIDATION_INVALID_FILTER",
  "details": {
    "field": "warranty_status",
    "allowed_values": ["active", "expired", "expiring_soon"]
  }
}

Invalid Date Format

{
  "error": "ValidationError",
  "message": "Invalid date format. Expected YYYY-MM-DD",
  "code": "VALIDATION_INVALID_DATE_FORMAT",
  "details": {
    "field": "date_from",
    "provided": "01/15/2024",
    "expected": "2024-01-15"
  }
}

Advanced Filtering

Multiple Values (OR Logic)

Some filters support multiple values:

GET /api/products?brand=Apple,Samsung&category=Electronics,Accessories

Returns products that are:

• (Apple OR Samsung) AND (Electronics OR Accessories)

Range Filters

Date ranges can be specified:

GET /api/products?purchase_date_from=2024-01-01&purchase_date_to=2024-12-31

Null/Empty Filters

Filter for null or empty values:

GET /api/products?serial_number=null

Related

• Pagination - Paginate filtered results
• Error Codes - Filter validation errors
• Products API - Product endpoints
• Claims API - Claims endpoints