Category

The category module provides CRUD for the internal category taxonomy used to group ACL permissions (see the Categories entity). All endpoints require Bearer JWT plus a specific ACL permission. The DTO body is currently empty in code — FE should not send free-form fields because forbidNonWhitelisted: true will reject them.

Property	Value
Base URL	{HOST}/v1
Auth	Bearer JWT (header Authorization) or access_token cookie
Content-Type	application/json
Error envelope	{ "message": string | string[], "statusCode": number, "error": string }
Validation	Global ValidationPipe · whitelist: true, forbidNonWhitelisted: true · unknown fields → 400
Related modules	acl (permission groupings), authentication
Document version	v1 · 2026-05-20
Audience	Internal FE devs (mobile + web)

Summary

Five standard REST endpoints to manage the Categories entity. The DTOs CreateCategoryDto and UpdateCategoryDto are currently empty — the service is still a stub. FE may assume a minimal shape until the backend fills in the fields. Each endpoint is guarded by a separate ACL permission (create-category, read-category, update-category, delete-category).

Method	Path	Auth	Summary
POST	/v1/categories	bearer	Create a new category (permission create-category)
GET	/v1/categories	bearer	List all categories (permission read-category)
GET	/v1/categories/:id	bearer	Detail of one category (permission read-category)
PATCH	/v1/categories/:id	bearer	Update a category (permission update-category)
DELETE	/v1/categories/:id	bearer	Soft delete a category (permission delete-category)

Implementation notes

• The service still uses string stub returns ("This action returns all category" etc.). After the ResponseInterceptor wraps it, FE will receive { status, statusCode, message, data: "<string stub>" }. Do not hard-code parsing — wait for the backend release that fills in the service.
• The :id parameter is not yet validated via ParseUUIDPipe. The service does +id (cast to number) — FE should send a numeric string until the backend is migrated to UUID.
• The Categories entity has columns name (unique), display_name, description, and a permissions[] relation. The future DTO fields will likely mirror this.

---

POST /v1/categories bearer

Create a new category. The DTO is currently empty so the server rejects any extra field (forbidNonWhitelisted). The endpoint is set up for admins managing the permission taxonomy.

bearer create-category

Request body — CreateCategoryDto

Field	Type	Required	Notes
(empty)	—	—	The DTO does not define any field yet; send body {}. Unknown fields will cause a 400.

Example request

{}

Response — 201 Created

{
  "status": "success",
  "statusCode": 201,
  "message": "Success",
  "data": "This action adds a new category"
}

The data body is a stub until the final service is implemented. Make sure FE treats the response as opaque until the backend ships.

Errors

Status	When it occurs
400 Bad Request	Body contains non-whitelisted fields
401 Unauthorized	Bearer/cookie is invalid
403 Forbidden	Caller does not have the create-category permission

---

GET /v1/categories bearer

Retrieve all categories. No pagination/filter yet; the service is still a stub.

bearer read-category

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Success",
  "data": "This action returns all category"
}

Errors

Status	When it occurs
401 Unauthorized	Bearer/cookie is invalid
403 Forbidden	Missing the read-category permission

---

GET /v1/categories/:id bearer

Detail of one category by id. The service does a numeric cast (+id).

bearer read-category

Path params

Param	Type	Notes
id	string	Currently read as a numeric string by the service (+id). No ParseUUIDPipe.

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Success",
  "data": "This action returns a #1 category"
}

Errors

Status	When it occurs
401 Unauthorized	Bearer/cookie is invalid
403 Forbidden	Missing the read-category permission

---

PATCH /v1/categories/:id bearer

Update a category. The DTO is still PartialType(CreateCategoryDto) which is empty — body must be {}.

bearer update-category

Path params

Param	Type	Notes
id	string	See notes on the detail endpoint

Request body — UpdateCategoryDto

Field	Type	Required	Notes
(empty)	—	—	DTO PartialType(CreateCategoryDto) — no fields exposed

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Success",
  "data": "This action updates a #1 category"
}

Errors

Status	When it occurs
400 Bad Request	Unknown field in body
401 Unauthorized	Bearer/cookie is invalid
403 Forbidden	Missing the update-category permission

---

DELETE /v1/categories/:id bearer

Delete a category. The service is still a stub — the final implementation is expected to be a soft delete (the entity inherits from AuditableEntity, so deleted_at/deleted_by are present).

bearer delete-category

Path params

Param	Type	Notes
id	string	See notes on the detail endpoint

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Success",
  "data": "This action removes a #1 category"
}

Errors

Status	When it occurs
401 Unauthorized	Bearer/cookie is invalid
403 Forbidden	Missing the delete-category permission

---

Reference

Permissions used

• create-category — POST
• read-category — GET (list + detail)
• update-category — PATCH
• delete-category — DELETE

Entity Categories

• name (string, unique)
• display_name (string)
• description (text, optional)
• permissions[] (relation to ACL Permissions)
• • audit fields from AuditableEntity

Standard error envelope

{
  "message": "property foo should not exist",
  "statusCode": 400,
  "error": "Bad Request"
}

Common HTTP codes

• 400 body validation / non-whitelisted field
• 401 missing / expired token
• 403 permission mismatch
• 500 internal — the service stub can throw a raw error