Product Categories

Author: Products Team, NextGate Backend Last Updated: 2025-09-22 Version: v1.0

Short Description: The Product Categories API manages hierarchical product categorization with support for parent-child relationships, enabling organized product catalog structure with visual icons and activation states.

Hints:

  • Categories support unlimited depth hierarchy (parent → child → grandchild...)

  • Category names must be unique across the entire system

  • Icon URLs should point to publicly accessible images (preferably SVG or PNG)

  • Soft deletion preserves category relationships and history

  • Super Admin role required for most category management operations

Endpoints

1. Create Product Category

Purpose: Creates a new product category with optional parent relationship

Endpoint: POST /api/v1/products/categories

Access Level: 🔒 Protected (Requires Super Admin role)

Authentication: Bearer Token

Request Headers:

Header
Type
Required
Description

Authorization

string

Yes

Bearer {access_token}

Content-Type

string

Yes

application/json

Request JSON Sample:

{
  "categoryName": "Smartphones",
  "categoryDescription": "Mobile phones and smartphones from various brands",
  "categoryIconUrl": "https://cdn.example.com/icons/smartphone.svg",
  "parentCategoryId": "550e8400-e29b-41d4-a716-446655440000"
}

Request Body Parameters:

Parameter
Type
Required
Description
Validation

categoryName

string

Yes

Unique category name

Min: 1, Max: 100 characters, must be unique

categoryDescription

string

No

Category description

Max: 500 characters

categoryIconUrl

string

No

URL to category icon

Valid URL format, Max: 1000 characters

parentCategoryId

UUID

No

Parent category UUID for hierarchy

Must exist and be active

Response JSON Sample:

{
  "status": "success",
  "message": "Product category created successfully",
  "data": {
    "categoryId": "123e4567-e89b-12d3-a456-426614174000",
    "categoryName": "Smartphones",
    "categoryDescription": "Mobile phones and smartphones from various brands",
    "categoryIconUrl": "https://cdn.example.com/icons/smartphone.svg",
    "parentCategoryId": "550e8400-e29b-41d4-a716-446655440000",
    "parentCategoryName": "Electronics",
    "createdTime": "2025-09-22T14:30:00Z",
    "editedTime": "2025-09-22T14:30:00Z",
    "isActive": true,
    "createdBy": "admin-user-id",
    "editedBy": "admin-user-id"
  }
}

Response Fields:

Field
Description

categoryId

Unique identifier for the category

categoryName

The category name

categoryDescription

Category description

categoryIconUrl

URL to category icon

parentCategoryId

Parent category ID (null for root categories)

parentCategoryName

Parent category name for convenience

createdTime

Category creation timestamp

editedTime

Last modification timestamp

isActive

Whether category is active

createdBy

ID of user who created the category

editedBy

ID of user who last edited the category

Error Responses:

  • 400 Bad Request: Validation errors in request data

  • 401 Unauthorized: Invalid or missing authentication token

  • 403 Forbidden: Insufficient permissions (not Super Admin)

  • 404 Not Found: Parent category not found

  • 409 Conflict: Category name already exists

  • 422 Unprocessable Entity: Business validation errors

2. Update Product Category

Purpose: Updates an existing product category including hierarchy changes

Endpoint: PUT /api/v1/products/categories/{categoryId}

Access Level: 🔒 Protected (Requires Super Admin role)

Authentication: Bearer Token

Request Headers:

Header
Type
Required
Description

Authorization

string

Yes

Bearer {access_token}

Content-Type

string

Yes

application/json

Path Parameters:

Parameter
Type
Required
Description
Validation

categoryId

UUID

Yes

Category to update

Must exist

Request JSON Sample:

{
  "categoryName": "Smart Phones & Devices",
  "categoryDescription": "Updated description for smartphones and smart devices",
  "categoryIconUrl": "https://cdn.example.com/icons/smartphone-updated.svg",
  "parentCategoryId": "550e8400-e29b-41d4-a716-446655440000"
}

Request Body Parameters:

Parameter
Type
Required
Description
Validation

categoryName

string

Yes

Updated category name

Min: 1, Max: 100 characters, unique if changed

categoryDescription

string

No

Updated description

Max: 500 characters

categoryIconUrl

string

No

Updated icon URL

Valid URL format, Max: 1000 characters

parentCategoryId

UUID

No

New parent (null to make root)

Must exist and be active, cannot create circular reference

Response JSON Sample:

{
  "status": "success",
  "message": "Product category updated successfully",
  "data": {
    "categoryId": "123e4567-e89b-12d3-a456-426614174000",
    "categoryName": "Smart Phones & Devices",
    "categoryDescription": "Updated description for smartphones and smart devices",
    "categoryIconUrl": "https://cdn.example.com/icons/smartphone-updated.svg",
    "parentCategoryId": "550e8400-e29b-41d4-a716-446655440000",
    "parentCategoryName": "Electronics",
    "createdTime": "2025-09-22T14:30:00Z",
    "editedTime": "2025-09-22T14:35:00Z",
    "isActive": true,
    "createdBy": "admin-user-id",
    "editedBy": "admin-user-id"
  }
}

Error Responses:

  • 400 Bad Request: Validation errors in request data

  • 401 Unauthorized: Invalid or missing authentication token

  • 403 Forbidden: Insufficient permissions

  • 404 Not Found: Category or parent category not found

  • 409 Conflict: Category name already exists

  • 422 Unprocessable Entity: Circular reference or other business logic errors

3. Get Category by ID

Purpose: Retrieves detailed information about a specific category

Endpoint: GET /api/v1/products/categories/{categoryId}

Access Level: 🌐 Public

Authentication: None

Path Parameters:

Parameter
Type
Required
Description
Validation

categoryId

UUID

Yes

Category to retrieve

Must exist

Response JSON Sample:

{
  "status": "success",
  "message": "Product category retrieved successfully",
  "data": {
    "categoryId": "123e4567-e89b-12d3-a456-426614174000",
    "categoryName": "Smartphones",
    "categoryDescription": "Mobile phones and smartphones from various brands",
    "categoryIconUrl": "https://cdn.example.com/icons/smartphone.svg",
    "parentCategoryId": "550e8400-e29b-41d4-a716-446655440000",
    "parentCategoryName": "Electronics",
    "createdTime": "2025-09-22T14:30:00Z",
    "editedTime": "2025-09-22T14:30:00Z",
    "isActive": true,
    "createdBy": "admin-user-id",
    "editedBy": "admin-user-id"
  }
}

Error Responses:

  • 404 Not Found: Category not found

4. Get All Categories

Purpose: Retrieves all categories with optional filtering by active status

Endpoint: GET /api/v1/products/categories/all

Access Level: 🌐 Public

Authentication: None

Query Parameters:

Parameter
Type
Required
Description
Validation
Default

isActive

boolean

No

Filter by active status

true or false

null (all)

Response JSON Sample:

{
  "status": "success",
  "message": "Product categories retrieved successfully",
  "data": [
    {
      "categoryId": "550e8400-e29b-41d4-a716-446655440000",
      "categoryName": "Electronics",
      "categoryDescription": "Electronic devices and gadgets",
      "categoryIconUrl": "https://cdn.example.com/icons/electronics.svg",
      "parentCategoryId": null,
      "parentCategoryName": null,
      "createdTime": "2025-09-22T14:00:00Z",
      "editedTime": "2025-09-22T14:00:00Z",
      "isActive": true,
      "createdBy": "admin-user-id",
      "editedBy": "admin-user-id"
    },
    {
      "categoryId": "123e4567-e89b-12d3-a456-426614174000",
      "categoryName": "Smartphones",
      "categoryDescription": "Mobile phones and smartphones from various brands",
      "categoryIconUrl": "https://cdn.example.com/icons/smartphone.svg",
      "parentCategoryId": "550e8400-e29b-41d4-a716-446655440000",
      "parentCategoryName": "Electronics",
      "createdTime": "2025-09-22T14:30:00Z",
      "editedTime": "2025-09-22T14:30:00Z",
      "isActive": true,
      "createdBy": "admin-user-id",
      "editedBy": "admin-user-id"
    }
  ]
}

Error Responses:

  • 400 Bad Request: Invalid query parameters

5. Get All Categories (Paginated)

Purpose: Retrieves categories with pagination support for large datasets

Endpoint: GET /api/v1/products/categories/all-paged

Access Level: 🌐 Public

Authentication: None

Query Parameters:

Parameter
Type
Required
Description
Validation
Default

isActive

boolean

No

Filter by active status

true or false

null

page

integer

No

Page number (1-based)

Min: 1

1

size

integer

No

Items per page

Min: 1, Max: 100

10

Response JSON Sample:

{
  "status": "success",
  "message": "Product categories retrieved successfully",
  "data": {
    "content": [
      {
        "categoryId": "123e4567-e89b-12d3-a456-426614174000",
        "categoryName": "Smartphones",
        "categoryDescription": "Mobile phones and smartphones",
        "categoryIconUrl": "https://cdn.example.com/icons/smartphone.svg",
        "parentCategoryId": "550e8400-e29b-41d4-a716-446655440000",
        "parentCategoryName": "Electronics",
        "createdTime": "2025-09-22T14:30:00Z",
        "editedTime": "2025-09-22T14:30:00Z",
        "isActive": true,
        "createdBy": "admin-user-id",
        "editedBy": "admin-user-id"
      }
    ],
    "pageable": {
      "pageNumber": 0,
      "pageSize": 10,
      "sort": {
        "sorted": true,
        "direction": "DESC",
        "property": "createdTime"
      }
    },
    "totalElements": 25,
    "totalPages": 3,
    "last": false,
    "first": true,
    "numberOfElements": 10,
    "size": 10,
    "number": 0
  }
}

Error Responses:

  • 400 Bad Request: Invalid pagination parameters

6. Get Parent Categories

Purpose: Retrieves only top-level categories (no parent)

Endpoint: GET /api/v1/products/categories/parent-categories

Access Level: 🌐 Public

Authentication: None

Response JSON Sample:

{
  "status": "success",
  "message": "Parent categories retrieved successfully",
  "data": [
    {
      "categoryId": "550e8400-e29b-41d4-a716-446655440000",
      "categoryName": "Electronics",
      "categoryDescription": "Electronic devices and gadgets",
      "categoryIconUrl": "https://cdn.example.com/icons/electronics.svg",
      "parentCategoryId": null,
      "parentCategoryName": null,
      "createdTime": "2025-09-22T14:00:00Z",
      "editedTime": "2025-09-22T14:00:00Z",
      "isActive": true,
      "createdBy": "admin-user-id",
      "editedBy": "admin-user-id"
    }
  ]
}

7. Get Child Categories

Purpose: Retrieves all child categories of a specific parent category

Endpoint: GET /api/v1/products/categories/parent/{parentId}/children

Access Level: 🌐 Public

Authentication: None

Path Parameters:

Parameter
Type
Required
Description
Validation

parentId

UUID

Yes

Parent category ID

Must exist and be active

Response JSON Sample:

{
  "status": "success",
  "message": "Child categories retrieved successfully",
  "data": [
    {
      "categoryId": "123e4567-e89b-12d3-a456-426614174000",
      "categoryName": "Smartphones",
      "categoryDescription": "Mobile phones and smartphones",
      "categoryIconUrl": "https://cdn.example.com/icons/smartphone.svg",
      "parentCategoryId": "550e8400-e29b-41d4-a716-446655440000",
      "parentCategoryName": "Electronics",
      "createdTime": "2025-09-22T14:30:00Z",
      "editedTime": "2025-09-22T14:30:00Z",
      "isActive": true,
      "createdBy": "admin-user-id",
      "editedBy": "admin-user-id"
    },
    {
      "categoryId": "789e4567-e89b-12d3-a456-426614174000",
      "categoryName": "Laptops",
      "categoryDescription": "Portable computers and laptops",
      "categoryIconUrl": "https://cdn.example.com/icons/laptop.svg",
      "parentCategoryId": "550e8400-e29b-41d4-a716-446655440000",
      "parentCategoryName": "Electronics",
      "createdTime": "2025-09-22T14:45:00Z",
      "editedTime": "2025-09-22T14:45:00Z",
      "isActive": true,
      "createdBy": "admin-user-id",
      "editedBy": "admin-user-id"
    }
  ]
}

Error Responses:

  • 404 Not Found: Parent category not found

8. Delete Category

Purpose: Soft deletes a category (marks as inactive)

Endpoint: DELETE /api/v1/products/categories/{categoryId}

Access Level: 🔒 Protected (Requires Super Admin role)

Authentication: Bearer Token

Request Headers:

Header
Type
Required
Description

Authorization

string

Yes

Bearer {access_token}

Path Parameters:

Parameter
Type
Required
Description
Validation

categoryId

UUID

Yes

Category to delete

Must exist and be active

Response JSON Sample:

{
  "status": "success",
  "message": "Product category deleted successfully"
}

Error Responses:

  • 401 Unauthorized: Invalid or missing authentication token

  • 403 Forbidden: Insufficient permissions

  • 404 Not Found: Category not found or already inactive

  • 422 Unprocessable Entity: Category has active child categories or products

9. Activate Category

Purpose: Reactivates a previously deleted category

Endpoint: PATCH /api/v1/products/categories/{categoryId}/activate

Access Level: 🔒 Protected (Requires Super Admin role)

Authentication: Bearer Token

Request Headers:

Header
Type
Required
Description

Authorization

string

Yes

Bearer {access_token}

Path Parameters:

Parameter
Type
Required
Description
Validation

categoryId

UUID

Yes

Category to activate

Must exist and be inactive

Response JSON Sample:

{
  "status": "success",
  "message": "Product category activated successfully"
}

Error Responses:

  • 401 Unauthorized: Invalid or missing authentication token

  • 403 Forbidden: Insufficient permissions

  • 404 Not Found: Category not found or already active

Quick Reference Guide

Common HTTP Status Codes

  • 200 OK: Successful GET/PUT/PATCH request

  • 201 Created: Successful POST request

  • 204 No Content: Successful DELETE request

  • 400 Bad Request: Invalid request data or parameters

  • 401 Unauthorized: Authentication required/failed

  • 403 Forbidden: Insufficient permissions (not Super Admin)

  • 404 Not Found: Category not found

  • 409 Conflict: Category name already exists

  • 422 Unprocessable Entity: Business logic validation errors

Authentication Types

  • Bearer Token: Include Authorization: Bearer your_token in headers

  • None: No authentication required for public read operations

Data Format Standards

  • Dates: Use ISO 8601 format (2025-09-22T14:30:00Z)

  • UUIDs: Standard UUID format (550e8400-e29b-41d4-a716-446655440000)

  • URLs: Must be valid HTTP/HTTPS URLs for icons

  • Names: Must be unique across all categories

Category Hierarchy Rules

  • Root categories have parentCategoryId: null

  • Child categories reference parent via parentCategoryId

  • Circular references are prevented

  • Deleting a parent category requires handling child categories first

  • Maximum recommended depth: 5 levels for performance

Business Rules

Category Creation

  • Category names must be unique across the entire system

  • Icon URLs are optional but recommended for better UX

  • Parent categories must be active to accept child categories

  • Only Super Admins can create/modify categories

Category Deletion

  • Soft deletion marks category as inactive (isActive: false)

  • Categories with active child categories cannot be deleted

  • Categories with products cannot be deleted directly

  • Deleted categories can be reactivated by Super Admins

Hierarchy Management

  • Moving categories between parents is supported

  • Circular references are automatically prevented

  • When moving a category, all descendants move with it

  • Root categories can be converted to child categories and vice versa

PreviousProduct Management ServiceNextProducts Management

Last updated