12 — API Mapping (Search Module)

• 1. Endpoint inventory
• 2. Query parameters (exact)
• 3. Success response (exact shape)
• 4. Empty query response
• 5. Error responses (client-relevant)
• 6. Request example (curl)
• 7. Client mapping (widget → endpoint)
• 8. Non-goals

Exact wire contract for global search. Envelope shapes are authoritative from 00-shared/07_API_Conventions.md (success/error envelopes, pagination meta, error codes, rate limits). Endpoint facts from search.controller.ts, search.service.ts, search-query.dto.ts.

1. Endpoint inventory

• Base URL https://api.<domain>/api/v1 (00-shared/07 §1).
• Auth: Authorization: Bearer <accessToken> — JwtAuthGuard (search.controller.ts:3,10); Swagger @ApiBearerAuth() (:9).
• This is the only endpoint in the module. Plan-only: (planned) coaching-index extension needs no new endpoint (same GET /search — docs/IMPLEMENTATION_PLAN.md:771).

2. Query parameters (exact)

Out-of-range page/limit, non-integer values → 400 VALIDATION_ERROR (00-shared/07 §3).

3. Success response (exact shape)

{
  "success": true,
  "message": "OK",
  "data": [
    {
      "entityType": "Student",
      "entityId": "66f1c0a5e8b2c1d4f5a6b7c8",
      "title": "Rahul Sharma",
      "description": "rahul@school.edu",
      "tags": ["grade5"]
    }
  ],
  "meta": { "page": 1, "limit": 20, "totalItems": 1, "totalPages": 1,
            "hasNext": false, "hasPrevious": false },
  "timestamp": "2026-08-03T09:00:00.000Z",
  "requestId": "req-…"
}

• data = array of SearchResult (search.service.ts:10-16,51-57).
• meta = buildPaginationMeta(page, limit, totalItems) (pagination-query.dto.ts:41-55); note totalPages never drops below 1 (:46).
• totalItems = full-text count (search.service.ts:37); when entityType filtering trims a page, totalItems is replaced by the filtered page length (search.service.ts:44-49) — see QA-14 §7.
• Relevance score (textScore) is used for sort only and never serialized (search-index.repository.ts:28-33; search.service.ts:51-57).

4. Empty query response

q blank/whitespace → data: [], meta.totalItems: 0, totalPages: 1 (search.service.ts:28-30). 200, not an error.

5. Error responses (client-relevant)

Server-side resilience: $text failure is caught and retried via regex fallback before any error reaches the client (search.service.ts:35-41).

6. Request example (curl)

GET /api/v1/search?q=rahul%20sharma&entityType=Student&page=1&limit=20
Authorization: Bearer <accessToken>

7. Client mapping (widget → endpoint)

8. Non-goals

• No POST /search, no bulk, no suggestions, no history endpoints — anything beyond GET /search is (forward-looking) / (planned).
• Search results are not cached in Redis today — RedisCacheService (redis-cache.service.ts:16-19) is available but unwired (proposed).