Search Module - API & Integration Guide

1. Scope

Search is implemented on product endpoints only.

• Admin product search: GET /api/admin/products
• Mobile product search: GET /api/mobile/products

2. Auth & Permissions

• Admin route: JWT + RoleGuard + @Permissions(Products_READ)
• Mobile route: public/mobile endpoint with Redis-backed rate limiting

3. Query Behavior

Both endpoints support:

• search (trimmed, typo-tolerant)
• sort=relevance (title trigram similarity)
• order=asc|desc
• pagination via shared QueryDto fields

Admin route also supports product admin filters (status, isSellable, etc.).

4. Search Strategy

• ILIKE on product title/description
• EXISTS subqueries for category/tag names
• similarity(product.title, search) > SEARCH_SIMILARITY_THRESHOLD (default 0.3)

5. Endpoints

6. Rate Limits

• Admin products: CATALOG_ADMIN_PRODUCT_SEARCH_RATE_LIMIT / CATALOG_ADMIN_PRODUCT_SEARCH_RATE_WINDOW_SECONDS
• Mobile products: CATALOG_CUSTOMER_PRODUCT_SEARCH_RATE_LIMIT / CATALOG_CUSTOMER_PRODUCT_SEARCH_RATE_WINDOW_SECONDS

7. Examples

GET /api/admin/products?search=markt&sort=relevance&order=desc&page=1&size=20

GET /api/mobile/products?search=candle stick&sort=relevance&order=desc&page=1&size=20

8. Edge Cases

• Empty/blank search: search block is skipped
• Invalid enum filters: DTO validation error
• Rate limit exceeded: 429
• Redis rate-limit/cache failure: fail-open for limiter, DB fallback for data path

See Also

• Feature Guide: See Search - Feature List for feature details.
• Backend Reference: See Catalog Product - Backend Documentation for search implementation details.