Catalog - API Reference

Audience: Frontend engineers, mobile engineers, backend engineers, QA, and API consumers. Scope: Admin, storefront and job-facing APIs owned by the Catalog module (categories, brands, brand series, tags, jobs, search).

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

4.1 Admin categories — /api/admin/catalog/categories

4.2 Admin brands — /api/admin/catalog/brands

4.3 Admin brand series — /api/admin/catalog/brand-series

Same 11-route shape as brands with BrandSeries_* permissions; create requires an owning brand (404 BRAND_SERIES_BRAND_NOT_FOUND, 409 BRAND_SERIES_BRAND_DELETED); reorder is sibling-scoped per brand (CATALOG_REORDER_MIXED_PARENT on mixed brands).

4.4 Admin jobs — /api/admin/catalog/jobs

4.5 Storefront — /api/mobile/catalog/*

Storefront series base is /series (not brand-series); the admin path is /brand-series.

5. Auth, Identity, and Permissions

Idempotency: Idempotency-Key required on import/export submit (scopes catalog-job-import / catalog-job-export). Missing → 400 IDEMPOTENCY_KEY_REQUIRED; replay with different payload → 409 IDEMPOTENCY_KEY_CONFLICT; in-flight → 409 IDEMPOTENCY_REQUEST_IN_PROGRESS.

6. DTO and Model Reference

6.1 CreateCategoryDto / UpdateCategoryDto

MoveCategoryDto { parentId: UUID v7 \| null } — required but nullable (null = root). CategoryVisibilityDto { isVisible: boolean }.

6.2 CreateCatalogBrandDto / CreateCatalogBrandSeriesDto

Brand: name (2..150, required), description (max 2000), slug, logoUrl, logoAlt (requires url), seoTitle, seoDescription. Series adds required brandPublicId (UUID v7). No displayOrder in create payloads — ordering is set via reorder.

6.3 Bulk DTOs

CatalogBulkIdsDto { publicIds: string[] } — non-empty UUID v7 array; duplicates deduped before the 100-item cap (409 CATALOG_BULK_LIMIT_EXCEEDED). CatalogBulkVisibilityDto adds isVisible. CatalogReorderDto { publicIds: string[] } — index position becomes displayOrder.

6.4 Query DTOs

QueryDto base: pagination (true), page (1), size (20, max 100), sort (updatedAt), order (desc). Category adds parentId, deletedOnly; brand adds includeDeleted; series adds includeDeleted, brandPublicId; jobs add kind, entity, status. Sortable fields: name, displayOrder, createdAt, updatedAt (jobs: createdAt, updatedAt, finishedAt).

7. Enum Reference

8. Endpoint Reference

8.1 GET /api/mobile/catalog/categories/:slug

Purpose

Category detail for a storefront category page. Accepts a current or retired slug; returns canonicalSlug so the frontend can redirect.

Auth and Permissions

@Public(), PUBLIC_READ 60/min, no permission.

Response

200 — { publicId, name, canonicalSlug, description, parentId, imageUrl, imageAlt, seoTitle, seoDescription }. parentId is null when the parent is soft-deleted or hidden — a deleted parent's id is never returned.

Error Cases

8.2 POST /api/admin/catalog/categories

Purpose

Create a category (optionally under a parent). Guarded by the tree invariants: parent liveness, depth cap.

Auth and Permissions

JwtAuthGuard, RoleGuard, IpThrottlerGuard; Categories_CREATE; ADMIN_WRITE 10/min; no idempotency header (create is not idempotent-guarded).

Request

Body per §6.1.

Response

201 — { publicId, name, slug, description, parentId, depth, displayOrder, isVisible, effectiveVisible, imageUrl, imageAlt, seoTitle, seoDescription, createdAt, updatedAt, deletedAt }.

Side Effects

category + category_slug rows in one transaction (advisory lock first when parented); activity record; cache invalidation.

Error Cases

8.3 PATCH /api/admin/catalog/categories/:publicId/move

The only parent-mutating route. Body { parentId: null } moves to root. 404 CATEGORY_NOT_FOUND/CATEGORY_PARENT_NOT_FOUND; 409 CATEGORY_PARENT_DELETED, CATEGORY_CIRCULAR_HIERARCHY, CATEGORY_MAX_DEPTH_EXCEEDED. Side effect: one-statement subtree rewrite.

8.4 DELETE /api/admin/catalog/:entity/:publicId (categories, brands, brand-series)

200 message-only body. 404 entity not found; 409 already deleted / has active children (category) / has active series (brand). Restore: POST /:publicId/restore, 200 with the entity payload; 409 not-deleted.

8.5 Bulk and reorder

POST /bulk/{delete,restore,visibility} — 200 with { succeeded: string[], failures: [{ publicId, errorCode }] }; per-item failures never roll back the batch; duplicates count once. PATCH /reorder — 200 message-only; the deduplicated set must exactly equal the alive sibling set (409 CATALOG_REORDER_INVALID_ITEM / CATALOG_REORDER_MIXED_PARENT).

8.6 POST /api/admin/catalog/jobs/import

multipart/form-data (file, entity). CSV/XLSX, 25 MB, 50,000 rows. Entity-specific permission re-check. Returns 200 with the queued job.

8.7 POST /api/admin/catalog/jobs/export

JSON { entity, includeDeleted?, search? }; 200 with the queued job. > 50,000 matching rows fails the job (CATALOG_EXPORT_TOO_LARGE).

8.8 POST /api/admin/catalog/jobs/:publicId/cancel

200 with the job row; 404 CATALOG_JOB_NOT_FOUND; 409 CATALOG_JOB_NOT_CANCELLABLE from a terminal state. Cooperative: a processing import aborts and rolls back.

8.9 GET /api/admin/catalog/jobs(/:publicId)

List (paginated, filters, ordered by createdAt; page cap → 400 PAGINATION_LIMIT_TOO_LARGE) and detail (adds startedAt, isStalled, retained errors).

8.10 GET /api/admin/catalog/jobs/import-template

Downloads the column template for an import file — header row only, no example row, because a downloadable import file is eventually uploaded unmodified and a data row would create junk. Zero rows is a no-op.

entity is one of category, brand, brand_series.

Permission Catalog_READ — the file carries no data, only column names. Rate limit ADMIN_READ 30/min. Returns 200 as text/csv; charset=utf-8 with Content-Disposition: attachment. An unknown entity fails DTO validation with 400.

Columns: category -> name, slug, description, parentSlug, displayOrder, isVisible, imageUrl, imageAlt, seoTitle, seoDescription; brand swaps the image pair for logoUrl, logoAlt and drops parentSlug; brand_series adds a required brandSlug.

The list is generated from the same constant the row builder's fields are typed against, so a column cannot silently diverge from what the parser reads: satisfies rejects a column that is not a row field, an Exclude assertion rejects a row field with no column, and a round-trip spec parses the emitted template back through the real builder.

Route ordering is load-bearing — this literal segment is declared above @Get(":publicId") in the controller. Declared after it, the wildcard swallows the path and the request fails as "publicId must be a UUID".

8.11 Tag endpoints

Admin /api/admin/catalog/tags (list/detail/create(201)/update/visibility/delete(200)/restore(200); Tags_*; errors TAG_NOT_FOUND, TAG_SLUG_ALREADY_EXISTS, TAG_ALREADY_DELETED, TAG_NOT_DELETED, TAG_HAS_LINKED_PRODUCTS). Storefront /api/mobile/catalog/tags (list/detail by slug; 404 TAG_NOT_FOUND).

8.12 GET /api/mobile/catalog/category-tree

Purpose

The whole storefront navigation in one request: every visible root category, each with its visible direct children.

It exists because no other customer response exposed a category's parent. GET /categories filters parentId IS NULL and its DTO carries no parent field, so a consumer could only recover the hierarchy by calling GET /categories/{slug}/breadcrumbs once per descendant — up to ~95 requests to render one menu, against a shared per-IP budget. That is what this endpoint replaces.

Depth is 1. A child carries no children of its own. A grandchild is not returned.

Source Evidence

Auth and Permissions

@Public(), IpThrottlerGuard + PUBLIC_HIGH_FREQUENCY 300/min, no permission.

The budget differs from the rest of the storefront catalog surface on purpose: this renders in the shared navigation on every page view, which is what PUBLIC_HIGH_FREQUENCY names, while /categories is an ordinary content read at PUBLIC_READ 60/min.

Request

No parameters. No query string, no body. Unknown query parameters are rejected by the global ValidationPipe's forbidNonWhitelisted.

Response

200 — an array of nodes in the standard envelope:

{
  "message": "Category tree fetched successfully",
  "data": [
    {
      "publicId": "01a0192f-31bf-71ee-8bc3-f3e0cbf7e5e3",
      "name": "Smartphones",
      "slug": "smartphones",
      "description": "Discover the latest smartphones…",
      "imageUrl": "http://localhost:5002/public/thumbnail/KAHfnL.webp",
      "imageAlt": "Latest smartphones and mobile phones",
      "displayOrder": 1,
      "children": [
        {
          "publicId": "01a01935-d765-7003-974f-ffbb32477c56",
          "name": "Android Phones",
          "slug": "android-phones",
          "description": "Explore Android smartphones…",
          "imageUrl": "https://cdn.example.com/categories/android-phones.jpg",
          "imageAlt": "Android smartphones",
          "displayOrder": 1
        }
      ]
    }
  ]
}

children is always present, [] for a childless root. A consumer may treat it as required.

Ordering is roots by displayOrder then id, and children by displayOrder then id within their own root — the same ordering GET /categories uses. The database does the ordering; a consumer that re-sorts is stating a second opinion about the same question.

Side Effects

None. One read, no writes, no cache population, no queue job. There is deliberately no server-side cache: the sole consumer caches the response for an hour on its own side.

Error Cases

There is no 404 and no 400. An empty catalogue is 200 with data: [], because "no categories" is a valid state of the store rather than a missing resource.

Edge Cases

The caps exist because SlugOwnershipService.getCurrentSlugs uses an unchunked inArray, which has a hard ceiling at Postgres's 65,535 bind parameters. Truncation is deterministic — by displayOrder, never arbitrary — and never silent.

Example Requests

curl -s http://localhost:5002/api/mobile/catalog/category-tree

Consistency

One statement, one snapshot. Roots and children are read by a single UNION ALL rather than two queries, so a category demoted from root to child between two reads cannot appear twice in one response, and a promoted one cannot vanish. That race is absent rather than mitigated — which is also why there is no transaction here.

Slug resolution runs as two further batched statements (one per level, never one per node), so a request issues three statements in total. The claim is that the tree rows come from one snapshot, not that the request makes one round trip.

8.13 GET /api/mobile/catalog/categories

Purpose

Visible root categories, flat. parentId IS NULL — it does not describe the hierarchy; use 8.12 for that.

Auth and Permissions

@Public(), PUBLIC_READ 60/min, no permission.

Response

200 — [{ publicId, name, slug, description, imageUrl, imageAlt, displayOrder }], ordered by displayOrder then id, capped at CATALOG_CUSTOMER_ROOT_CATEGORY_LIST_MAX (200).

Edge Cases

That last row is a behaviour change. This endpoint previously emitted slug: "" for such a row, which put a category in the list whose link resolved to the collection root and whose own detail route 404'd. It now matches 8.12, because two public endpoints disagreeing about which categories exist is worse than either answer: the home page would show a category the navigation does not.

9. Flow Diagrams

9.1 Route Ownership

9.2 Request Sequence (move)

9.3 Error Branch (delete category)

10. Pagination, Sorting, Filtering, and Search

Search ranking is fixed: similarity DESC, display_order ASC, id ASC; term < 2 chars = no search; terms > 64 chars skip the Redis cache.

11. Caching, Jobs, and External Integrations

13. Mandatory Deep API Documentation Pack

13.1 Route-by-Route Completeness Matrix

13.2 Request/Response Exhaustiveness

Covered in §8: minimal create payloads (§6.1), success responses (§8.1, §8.2), empty-list behavior (admin lists return data: [] + pagination metadata; storefront bounded lists return []), validation error (400 VALIDATION_FAILED representative), domain errors per endpoint (§8 error tables), rate-limit behavior (throttler 429), admin permission errors (403).

13.3 API Diagram Pack

Route ownership (§9.1), sequence per endpoint family (§9.2, backend §7), activity diagrams per mutation family (§9.3, feature §6), error decision trees (§9.3), async/job flow (backend §7.2), cache flow (backend §8).

13.4 Consumer Integration Notes

13.5 API Tradeoffs and Rationale

13.6 API Change Impact

14. Zero-Omission API Checklist

• Every controller route is documented (§4, §8, §13.1).
• Every parent route prefix and runtime URL is documented (§2, §4).
• Every DTO field, enum, default, transform and validator is documented (§6, §7).
• Every response field, nullable field, generated field and omitted raw entity field is documented (§8).
• Every auth, guard, permission, public decorator and guest identity branch is documented (§5).
• Every success, validation, auth, permission, not-found, conflict, rate-limit and server-error branch is documented (§8).
• Every DB read/write, cache hit/miss/invalidation, queue job, audit log and external call is documented (§11, backend §8/§9).
• Every route has examples for minimal request, success response and representative failures (§8).
• Every endpoint family has route, sequence, activity and error diagrams (§9, backend §7).
• Every tradeoff and compatibility risk is documented (§13.5, §13.6).
• The API doc links to backend and features/flows (§1, See Also).

15. Integration Checklist

• Every route from controllers is documented.
• Every DTO field is documented.
• Every enum value is documented.
• Every response envelope is documented.
• Every error code is documented.
• Every auth guard and permission is documented.
• Every cache key, queue job and external call is documented.
• Every diagram matches the current code.
• The API doc links to backend and features/flows.

See Also

• Backend doc: /docs/developer/catalog/backend
• Features and flows doc: /docs/developer/catalog/feature
• TDD: not yet published