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 ) 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 ) 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 ) 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 ) 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 ) 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 ) 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 ) 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