starr-philproperties/controllers/admin/documentation/categories.md

Categories Controller Documentation

File: controllers/admin/categories.controller.js
Base URL: /api/admin/categories
Guards: authenticate → requireAdmin() → adminLimiter

---

Table of Contents

• Get All Categories
• Get Single Category
• Create Category
• Update Category
• Archive Category
• Restore Category

---

Notes

• slug is auto-generated from name on create and update: lowercased, trimmed, non-alphanumeric runs replaced with -.
• slug and name must be unique across all categories (including archived ones).
• paranoid: false is used on GET All and GET One, so archived categories are visible.

---

Get All Categories

GET /api/admin/categories

Returns all categories ordered alphabetically by name. Includes archived rows.

Response 200

{
  "status": "success",
  "message": "Categories retrieved.",
  "data": [
    {
      "id": 1,
      "name": "Business",
      "slug": "business",
      "description": "Business courses",
      "is_active": true,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "deletedAt": null
    }
  ]
}

---

Get Single Category

GET /api/admin/categories/:id

Returns one category. Includes archived.

Response 200

{
  "status": "success",
  "message": "Category retrieved.",
  "data": { "id": 1, "name": "Business", "slug": "business", ... }
}

Error Responses

Status	Message
404	Category not found.

---

Create Category

POST /api/admin/categories

Request Body

Field	Type	Required	Description
name	string	Yes	Display name. Must be unique.
description	string	No	Optional description.
is_active	boolean	No	Default: true

Response 201

{
  "status": "success",
  "message": "Category created.",
  "data": { "id": 2, "name": "Design", "slug": "design", "is_active": true, ... }
}

Error Responses

Status	Message
400	name is required.
409	A category with that name already exists.

---

Update Category

PUT /api/admin/categories/:id

Full update. Only non-null/undefined fields are changed. slug is re-generated if name changes.

Request Body

Field	Type	Required	Description
name	string	No	New display name.
description	string	No
is_active	boolean	No

Response 200

{
  "status": "success",
  "message": "Category updated.",
  "data": { ... }
}

Error Responses

Status	Message
404	Category not found.
409	A category with that name already exists.

---

Archive Category

DELETE /api/admin/categories/:id

Soft-deletes the category (deletedAt set).

Response 200

{ "status": "success", "message": "Category archived." }

Error Responses

Status	Message
404	Category not found.

---

Restore Category

POST /api/admin/categories/:id/restore

Restores a soft-deleted category.

Response 200

{
  "status": "success",
  "message": "Category restored.",
  "data": { ... }
}

Error Responses

Status	Message
404	Category not found.