Event Categories Management API

Author: Josh S. Sakweli, Backend Lead Team
Last Updated: 2025-12-11
Version: v1.0

Base URL: https://api.nexgate.com/api/v1

Short Description: The Event Categories Management API provides administrative functionality for managing event categories in the Nexgate platform. This API enables authorized users (Staff Admin/Super Admin) to create, update, retrieve event categories, and seed default categories for event classification and organization.

Hints:

All POST/PUT endpoints require STAFF_ADMIN or SUPER_ADMIN role
GET endpoints are accessible to all authenticated users
Category names are unique (case-insensitive)
Slugs are auto-generated from category names and must be unique
Slug collisions are handled automatically by appending numbers (e.g., music-1, music-2)
Categories support featured and active status flags
Pagination is 1-indexed (page=1 for first page), default size is 10 items
Event count tracks number of events in each category (updated automatically)
Color codes must be valid hex format (#FF5733 or #F57)
Icon URLs must be valid image URLs or paths

Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-12-11T10:30:45",
  "data": "Error description"
}

Standard Response Fields

Field	Type	Description
`success`	boolean	Always `true` for successful operations, `false` for errors
`httpStatus`	string	HTTP status name (OK, BAD_REQUEST, NOT_FOUND, etc.)
`message`	string	Human-readable message describing the operation result
`action_time`	string	ISO 8601 timestamp of when the response was generated
`data`	object/string	Response payload for success, error details for failures

HTTP Method Badge Standards

For better visual clarity, all endpoints use colored badges for HTTP methods with the following standard colors:

GET - GET - Green (Safe, read-only operations)
POST - POST - Blue (Create new resources)
PUT - PUT - Yellow (Update/replace entire resource)

EventCategoryResponse Structure

This is the standard response structure returned by all category endpoints:

{
  "categoryId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Music & Concerts",
  "slug": "music-concerts",
  "description": "Live music performances, concerts, festivals, and DJ events",
  "iconUrl": "https://cdn.nexgate.com/icons/music.svg",
  "colorCode": "#E91E63",
  "isActive": true,
  "isFeatured": true,
  "eventCount": 125,
  "createdBy": "admin_user",
  "createdAt": "2025-12-11T10:30:45",
  "updatedBy": "admin_user",
  "updatedAt": "2025-12-11T14:20:30"
}

Response Field Descriptions

Field	Type	Description
categoryId	string (UUID)	Unique identifier for the category
name	string	Category display name (unique, case-insensitive)
slug	string	URL-friendly identifier (auto-generated, unique)
description	string	Category description
iconUrl	string	URL or path to category icon image
colorCode	string	Hex color code for category theming (#RRGGBB or #RGB)
isActive	boolean	Whether category is active and visible
isFeatured	boolean	Whether category should be featured/highlighted
eventCount	integer	Number of events in this category
createdBy	string	Username of the admin who created the category
createdAt	string	ISO 8601 timestamp of creation
updatedBy	string	Username of the admin who last updated (null if never updated)
updatedAt	string	ISO 8601 timestamp of last update (null if never updated)

Endpoints

1. Create Category

Purpose: Create a new event category (requires admin privileges)

Endpoint: POST {base_url}/e-events/categories

Access Level: 🔒 Protected (Requires Bearer Token Authentication + Admin Role)

Required Roles: ROLE_STAFF_ADMIN or ROLE_SUPER_ADMIN

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Request JSON Sample:

{
  "name": "Music & Concerts",
  "description": "Live music performances, concerts, festivals, and DJ events",
  "iconUrl": "https://cdn.nexgate.com/icons/music.svg",
  "colorCode": "#E91E63",
  "isActive": true,
  "isFeatured": true
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
name	string	Yes	Category name	Min: 2, Max: 100 characters
description	string	No	Category description	Max: 500 characters
iconUrl	string	No	URL or path to icon image	Must be valid image URL (jpg, jpeg, png, gif, svg, webp) or path starting with /icons/
colorCode	string	No	Hex color code	Must be valid hex format: #RRGGBB or #RGB (e.g., #FF5733 or #F57)
isActive	boolean	Yes	Whether category is active	Required boolean value
isFeatured	boolean	Yes	Whether category is featured	Required boolean value

Success Response: Returns standard EventCategoryResponse structure (see "EventCategoryResponse Structure" section above)

Success Response Message: "Category created successfully"

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Category created successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "categoryId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Music & Concerts",
    "slug": "music-concerts",
    "description": "Live music performances, concerts, festivals, and DJ events",
    "iconUrl": "https://cdn.nexgate.com/icons/music.svg",
    "colorCode": "#E91E63",
    "isActive": true,
    "isFeatured": true,
    "eventCount": 0,
    "createdBy": "admin_user",
    "createdAt": "2025-12-11T10:30:45",
    "updatedBy": null,
    "updatedAt": null
  }
}

Standard Error Types:

Application-Level Exceptions (400-499)

400 BAD_REQUEST: Category already exists (duplicate name)
401 UNAUTHORIZED: Authentication issues (empty, invalid, expired, or malformed tokens)
403 FORBIDDEN: Access denied (insufficient permissions - not admin)
404 NOT_FOUND: User not found or not authenticated
422 UNPROCESSABLE_ENTITY: Validation errors with detailed field information
500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

Already Exists - Duplicate Name (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Category already exists",
  "action_time": "2025-12-11T10:30:45",
  "data": "Category with name 'Music & Concerts' already exists"
}

Access Denied - Insufficient Permissions (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Access denied",
  "action_time": "2025-12-11T10:30:45",
  "data": "Access denied. Insufficient permissions."
}

Validation Error - Invalid Name (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "name": "Category name must be between 2 and 100 characters"
  }
}

Validation Error - Invalid Color Code (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "colorCode": "Color code must be a valid hex color (e.g., #FF5733 or #F57)"
  }
}

Validation Error - Invalid Icon URL (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "iconUrl": "Icon URL must be a valid image URL or path"
  }
}

2. Update Category

Purpose: Update an existing event category (requires admin privileges)

Endpoint: PUT {base_url}/e-events/categories/{categoryId}

Access Level: 🔒 Protected (Requires Bearer Token Authentication + Admin Role)

Required Roles: ROLE_STAFF_ADMIN or ROLE_SUPER_ADMIN

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
categoryId	string	Yes	UUID of the category to update	Must be valid UUID format

Request JSON Sample:

{
  "name": "Live Music & Concerts",
  "description": "Updated description for live music events",
  "iconUrl": "https://cdn.nexgate.com/icons/music-updated.svg",
  "colorCode": "#FF1744",
  "isActive": true,
  "isFeatured": false
}

Request Body Parameters (All Optional):

Parameter	Type	Required	Description	Validation
name	string	No	Updated category name	Min: 2, Max: 100 characters
description	string	No	Updated description	Max: 500 characters
iconUrl	string	No	Updated icon URL/path	Must be valid image URL or path
colorCode	string	No	Updated hex color code	Must be valid hex format: #RRGGBB or #RGB
isActive	boolean	No	Updated active status
isFeatured	boolean	No	Updated featured status

Success Response: Returns standard EventCategoryResponse structure with updated values

Success Response Message: "Category updated successfully"

Standard Error Types:

Application-Level Exceptions (400-499)

400 BAD_REQUEST: Category name already exists (when changing name to duplicate)
401 UNAUTHORIZED: Authentication issues
403 FORBIDDEN: Access denied (insufficient permissions - not admin)
404 NOT_FOUND: Category not found with given ID
422 UNPROCESSABLE_ENTITY: Validation errors
500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

Not Found - Invalid Category ID (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Category not found",
  "action_time": "2025-12-11T10:30:45",
  "data": "Category not found with ID: 550e8400-e29b-41d4-a716-446655440000"
}

Already Exists - Duplicate Name (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Category already exists",
  "action_time": "2025-12-11T10:30:45",
  "data": "Category with name 'Sports & Fitness' already exists"
}

3. Get Category by ID

Purpose: Retrieve a single category by its UUID

Endpoint: GET {base_url}/e-events/categories/{categoryId}

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
categoryId	string	Yes	UUID of the category to retrieve	Must be valid UUID format

Success Response: Returns standard EventCategoryResponse structure

Success Response Message: "Category retrieved successfully"

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Category retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "categoryId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Music & Concerts",
    "slug": "music-concerts",
    "description": "Live music performances, concerts, festivals, and DJ events",
    "iconUrl": "https://cdn.nexgate.com/icons/music.svg",
    "colorCode": "#E91E63",
    "isActive": true,
    "isFeatured": true,
    "eventCount": 125,
    "createdBy": "admin_user",
    "createdAt": "2025-12-11T10:30:45",
    "updatedBy": "admin_user",
    "updatedAt": "2025-12-11T14:20:30"
  }
}

Standard Error Types:

Application-Level Exceptions (400-499)

401 UNAUTHORIZED: Authentication issues
404 NOT_FOUND: Category not found with given ID
500 INTERNAL_SERVER_ERROR: Unexpected server errors

4. Get Category by Slug

Purpose: Retrieve a single category by its URL-friendly slug

Endpoint: GET {base_url}/e-events/categories/slug/{slug}

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
slug	string	Yes	URL-friendly slug of the category	Lowercase, hyphen-separated (e.g., music-concerts)

Example Request URL: https://api.nexgate.com/api/v1/e-events/categories/slug/music-concerts

Success Response: Returns standard EventCategoryResponse structure

Success Response Message: "Category retrieved successfully"

Standard Error Types:

Application-Level Exceptions (400-499)

401 UNAUTHORIZED: Authentication issues
404 NOT_FOUND: Category not found with given slug
500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Example:

Not Found - Invalid Slug (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Category not found",
  "action_time": "2025-12-11T10:30:45",
  "data": "Category not found with slug: non-existent-category"
}

5. Get All Categories

Purpose: Retrieve all event categories (unpaginated, complete list)

Endpoint: GET {base_url}/e-events/categories/all

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Categories retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": [
    {
      "categoryId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Music & Concerts",
      "slug": "music-concerts",
      "description": "Live music performances, concerts, festivals, and DJ events",
      "iconUrl": "https://cdn.nexgate.com/icons/music.svg",
      "colorCode": "#E91E63",
      "isActive": true,
      "isFeatured": true,
      "eventCount": 125,
      "createdBy": "admin_user",
      "createdAt": "2025-12-11T10:30:45",
      "updatedBy": null,
      "updatedAt": null
    },
    {
      "categoryId": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Sports & Fitness",
      "slug": "sports-fitness",
      "description": "Yoga, gym classes, marathons, tournaments, and outdoor activities",
      "iconUrl": "https://cdn.nexgate.com/icons/sports.svg",
      "colorCode": "#4CAF50",
      "isActive": true,
      "isFeatured": true,
      "eventCount": 89,
      "createdBy": "admin_user",
      "createdAt": "2025-12-11T10:30:45",
      "updatedBy": null,
      "updatedAt": null
    }
  ]
}

Success Response Fields:

Field	Description
data	Array of EventCategoryResponse objects (complete list, no pagination)

Standard Error Types:

Application-Level Exceptions (400-499)

401 UNAUTHORIZED: Authentication issues
500 INTERNAL_SERVER_ERROR: Unexpected server errors

6. Get Paginated Categories

Purpose: Retrieve event categories with pagination support

Endpoint: GET {base_url}/e-events/categories/paged

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (1-indexed)	Min: 1	1
size	integer	No	Number of items per page	Min: 1, Max: 100	10

Example Request URL: https://api.nexgate.com/api/v1/e-events/categories/paged?page=1&size=10

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Categories retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "content": [
      {
        "categoryId": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Music & Concerts",
        "slug": "music-concerts",
        "description": "Live music performances, concerts, festivals, and DJ events",
        "iconUrl": "https://cdn.nexgate.com/icons/music.svg",
        "colorCode": "#E91E63",
        "isActive": true,
        "isFeatured": true,
        "eventCount": 125,
        "createdBy": "admin_user",
        "createdAt": "2025-12-11T10:30:45",
        "updatedBy": null,
        "updatedAt": null
      }
    ],
    "pageable": {
      "pageNumber": 0,
      "pageSize": 10,
      "sort": {
        "sorted": false,
        "empty": true,
        "unsorted": true
      },
      "offset": 0,
      "paged": true,
      "unpaged": false
    },
    "totalPages": 1,
    "totalElements": 10,
    "last": true,
    "size": 10,
    "number": 0,
    "sort": {
      "sorted": false,
      "empty": true,
      "unsorted": true
    },
    "numberOfElements": 10,
    "first": true,
    "empty": false
  }
}

Success Response Fields:

Field	Description
content	Array of EventCategoryResponse objects for current page
totalPages	Total number of pages available
totalElements	Total number of categories across all pages
size	Number of items per page (requested size)
number	Current page number (0-indexed in response)
first	Boolean indicating if this is the first page
last	Boolean indicating if this is the last page
empty	Boolean indicating if the result set is empty

Standard Error Types:

Application-Level Exceptions (400-499)

401 UNAUTHORIZED: Authentication issues
500 INTERNAL_SERVER_ERROR: Unexpected server errors

7. Seed Categories

Purpose: Populate the database with default event categories (requires admin privileges)

Endpoint: POST {base_url}/e-events/categories/seed

Access Level: 🔒 Protected (Requires Bearer Token Authentication + Admin Role)

Required Roles: ROLE_STAFF_ADMIN or ROLE_SUPER_ADMIN

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Request Body: None (no body required)

Default Categories Seeded:

This endpoint creates the following 10 default categories (if they don't already exist):

Music & Concerts - Live music performances, concerts, festivals, and DJ events (Featured)
Sports & Fitness - Yoga, gym classes, marathons, tournaments, and outdoor activities (Featured)
Business & Networking - Professional meetups, conferences, workshops, and networking events (Featured)
Food & Drink - Food festivals, cooking classes, wine tastings, and dining experiences
Arts & Culture - Art exhibitions, theater, dance, museums, and cultural events
Education & Learning - Workshops, seminars, courses, bootcamps, and training sessions (Featured)
Social & Community - Parties, meetups, social clubs, game nights, and community events
Technology & Innovation - Tech talks, hackathons, product launches, and startup events
Wellness & Spirituality - Meditation, yoga retreats, healing workshops, and mindfulness events
Entertainment - Comedy shows, movie screenings, gaming, and entertainment events

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Categories seeded successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": [
    {
      "categoryId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Music & Concerts",
      "slug": "music-concerts",
      "description": "Live music performances, concerts, festivals, and DJ events",
      "iconUrl": "",
      "colorCode": "#E91E63",
      "isActive": true,
      "isFeatured": true,
      "eventCount": 0,
      "createdBy": "admin_user",
      "createdAt": "2025-12-11T10:30:45",
      "updatedBy": null,
      "updatedAt": null
    },
    {
      "categoryId": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Sports & Fitness",
      "slug": "sports-fitness",
      "description": "Yoga, gym classes, marathons, tournaments, and outdoor activities",
      "iconUrl": "",
      "colorCode": "#4CAF50",
      "isActive": true,
      "isFeatured": true,
      "eventCount": 0,
      "createdBy": "admin_user",
      "createdAt": "2025-12-11T10:30:45",
      "updatedBy": null,
      "updatedAt": null
    }
    // ... (remaining 8 categories)
  ]
}

Success Response Fields:

Field	Description
data	Array of EventCategoryResponse objects (newly created categories only, or all existing if none were created)

Behavior Notes:

Only creates categories that don't already exist (checked by name, case-insensitive)
If all 10 default categories already exist, returns the existing categories
All seeded categories are marked as active (isActive: true)
Categories marked as "Featured" have isFeatured: true
Event count starts at 0 for newly seeded categories
The authenticated admin user is set as createdBy for all new categories
Slugs are auto-generated from category names

Standard Error Types:

Application-Level Exceptions (400-499)

401 UNAUTHORIZED: Authentication issues
403 FORBIDDEN: Access denied (insufficient permissions - not admin)
404 NOT_FOUND: User not found or not authenticated
500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Example:

Access Denied - Not Admin (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Access denied",
  "action_time": "2025-12-11T10:30:45",
  "data": "Access denied. Insufficient permissions."
}

Quick Reference Guide

Common HTTP Status Codes

200 OK: Successful GET/POST/PUT request
400 Bad Request: Invalid request data or business rule violation (duplicate names)
401 Unauthorized: Authentication required/failed
403 Forbidden: Insufficient permissions (not admin)
404 Not Found: Resource not found (category, user)
422 Unprocessable Entity: Validation errors
500 Internal Server Error: Server error

Authentication & Authorization

Bearer Token: Include Authorization: Bearer your_token in headers
Required Roles for POST/PUT: ROLE_STAFF_ADMIN or ROLE_SUPER_ADMIN
GET Endpoints: Accessible to all authenticated users

Data Format Standards

Dates: ISO 8601 format (2025-12-11T14:30:00)
IDs: UUID format (e.g., 550e8400-e29b-41d4-a716-446655440000)
Slugs: Lowercase, hyphen-separated (e.g., music-concerts)
Color Codes: Hex format #RRGGBB or #RGB (e.g., #FF5733 or #F57)
Pagination: 1-indexed pages (page=1 for first page), default size=10

Category Name Rules

Minimum 2 characters, maximum 100 characters
Must be unique (case-insensitive check)
Automatically trimmed of whitespace
Used to auto-generate slug

Slug Generation Rules

Auto-generated from category name
Lowercase only
Special characters removed
Spaces replaced with hyphens
Duplicate hyphens removed
Leading/trailing hyphens removed
Collisions handled by appending numbers (e.g., music-1, music-2)

Icon URL Validation

Must be valid HTTP/HTTPS URL ending in image extension (jpg, jpeg, png, gif, svg, webp)
OR must be path starting with /icons/ ending in image extension
Examples:
- Valid: https://cdn.nexgate.com/icons/music.svg
- Valid: /icons/music.png
- Invalid: https://example.com/file.pdf

Color Code Validation

Must start with #
Must be 6-character hex (e.g., #FF5733) or 3-character hex (e.g., #F57)
Case-insensitive (A-F or a-f)
Examples:
- Valid: #FF5733, #F57, #e91e63
- Invalid: FF5733, #GG5733, #12345

Featured Categories

Categories with isFeatured: true are typically displayed prominently in UI:

Music & Concerts
Sports & Fitness
Business & Networking
Education & Learning

Event Count

Automatically updated when events are created/deleted in a category
Starts at 0 for new categories
Used for analytics and sorting popular categories

Revision #1
Created 11 December 2025 09:37:06 by Admin Qbit
Updated 11 December 2025 09:38:05 by Admin Qbit