Event Feedback API

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

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

Short Description: The Event Feedback API enables attendees to rate and review events after attendance. This API provides a simple 5-star rating system with optional comments, prevents duplicate feedback, ensures only attendees (non-organizers) can submit reviews, and allows anyone to view event feedback with pagination. The system supports escrow release decisions based on feedback quality and helps organizers improve future events.

Hints:

One Feedback Per User: Each user can only submit one feedback per event
Attendee Only: Event organizers cannot review their own events
5-Star Rating: Required rating from 1-5 stars
Optional Comments: Text reviews up to 1000 characters
Public Viewing: Anyone can view event feedback (paginated)
Chronological Order: Newest feedback first
Escrow Integration: Feedback may influence escrow release (future)
Simple Model: Focus on rating quality over complex metrics

Response Structure

EventFeedbackResponse

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "eventId": "770e8400-e29b-41d4-a716-446655440002",
  "eventTitle": "East African Tech Summit 2025",
  "userId": "660e8400-e29b-41d4-a716-446655440001",
  "userName": "johndoe",
  "rating": 5,
  "comment": "Amazing event! The speakers were excellent and the venue was perfect. Definitely attending next year!",
  "createdAt": "2025-12-18T10:30:45Z"
}

Paginated Response

{
  "success": true,
  "httpStatus": "OK",
  "message": "Feedbacks retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "content": [
      {
        "id": "uuid",
        "eventId": "uuid",
        "eventTitle": "East African Tech Summit 2025",
        "userId": "uuid",
        "userName": "johndoe",
        "rating": 5,
        "comment": "Great event!",
        "createdAt": "2025-12-18T10:30:45Z"
      }
    ],
    "pageable": {
      "pageNumber": 0,
      "pageSize": 20,
      "offset": 0
    },
    "totalElements": 145,
    "totalPages": 8,
    "last": false,
    "first": true,
    "numberOfElements": 20,
    "size": 20,
    "number": 0,
    "empty": false
  }
}

Endpoints

1. Create Feedback

Endpoint: POST /feedbacks/event/{eventId}

Access: 🔒 Authenticated Users (Non-Organizers)

Path Parameters:

Parameter	Type	Required	Description
eventId	string (UUID)	Yes	Event identifier

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token
Content-Type	string	Yes	application/json

Request Body:

{
  "rating": 5,
  "comment": "Amazing event! The speakers were excellent and the venue was perfect. Definitely attending next year!"
}

Request Parameters:

Parameter	Type	Required	Description	Validation
rating	integer	Yes	Star rating	Min: 1, Max: 5
comment	string	No	Text review	Max: 1000 characters

Success Response: Returns EventFeedbackResponse

Success Response Message: "Feedback submitted successfully"

HTTP Status Code: 201 CREATED

Behavior:

Validates user is authenticated
Validates event exists
Checks user is NOT the event organizer
Checks user hasn't already submitted feedback
Creates feedback record
Returns created feedback

Validation Rules:

✅ Rating must be 1-5 (integer)
✅ Comment optional, max 1000 chars
✅ One feedback per user per event
✅ Organizers cannot review own events
✅ Event must exist

Standard Error Types:

400 BAD_REQUEST: Invalid rating (not 1-5)
401 UNAUTHORIZED: Not authenticated
403 FORBIDDEN: Organizer trying to review own event
404 NOT_FOUND: Event not found
409 CONFLICT: Already submitted feedback

Error Response Examples:

Invalid Rating (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Rating must be at least 1",
  "action_time": "2025-12-11T10:30:45",
  "data": "Rating must be at least 1"
}

Organizer Cannot Review (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Event organizers cannot submit feedback for their own events.",
  "action_time": "2025-12-11T10:30:45",
  "data": "Event organizers cannot submit feedback for their own events."
}

Already Submitted (409):

{
  "success": false,
  "httpStatus": "CONFLICT",
  "message": "You have already provided feedback for this event",
  "action_time": "2025-12-11T10:30:45",
  "data": "You have already provided feedback for this event"
}

2. Get Event Feedbacks

Endpoint: GET /feedbacks/event/{eventId}?page=0&size=20

Access: 🔓 Public (No Authentication Required)

Path Parameters:

Parameter	Type	Required	Description
eventId	string (UUID)	Yes	Event identifier

Query Parameters:

Parameter	Type	Required	Description
page	integer	No	Page number (0-indexed, default: 0)
size	integer	No	Items per page (default: 20)

Success Response: Returns Spring Page object with EventFeedbackResponse items

Success Response Message: "Feedbacks retrieved successfully"

HTTP Status Code: 200 OK

Behavior:

Returns paginated list of feedback
Sorted by creation date (newest first)
No authentication required (public access)
Validates event exists

Pagination Details:

Zero-indexed pages (0, 1, 2...)
Default page size: 20
Max page size: 100 (recommended)
Includes total elements and pages

Standard Error Types:

404 NOT_FOUND: Event not found

Rating System

Star Ratings (1-5)

Rating	Meaning	Emoji	Description
5 ⭐⭐⭐⭐⭐	Excellent	😍	Outstanding event, exceeded expectations
4 ⭐⭐⭐⭐	Very Good	😊	Great event, minor improvements possible
3 ⭐⭐⭐	Good	🙂	Satisfactory event, met expectations
2 ⭐⭐	Fair	😐	Below expectations, needs improvement
1 ⭐	Poor	😞	Disappointing event, significant issues

Average Rating Calculation

Average = Sum of all ratings / Number of feedbacks

Example:

Ratings: 5, 5, 4, 5, 3, 4, 5, 5, 4, 5
Total: 45
Count: 10
Average: 4.5 stars

Display Format: 4.5 ⭐ (10 reviews)

Comment Guidelines

Character Limit

Maximum: 1000 characters
Recommended: 100-500 characters
Minimum: None (optional field)

Access Control

Who Can Submit Feedback?

Allowed:

✅ Any authenticated user
✅ Attendees (purchased tickets)
✅ Non-attendees (also allowed currently)

Not Allowed:

❌ Event organizers (for their own events)
❌ Users who already submitted feedback
❌ Unauthenticated users

Future Restriction (Recommended):

Only users who purchased tickets
Requires checking booking history
Prevents fake reviews

Who Can View Feedback?

Anyone (Public access):

✅ No authentication required
✅ Potential attendees researching events
✅ Event organizers viewing their reviews
✅ Platform admins

Use Cases

Submit Feedback After Event

POST /feedbacks/event/{eventId}
{
  "rating": 5,
  "comment": "Great event, highly recommend!"
}

User provides honest review after attending

View Event Reviews Before Booking

GET /feedbacks/event/{eventId}?page=0&size=20

Potential attendee checks reviews before purchasing tickets
Sees average rating and recent comments

Organizer Checks Feedback

GET /feedbacks/event/{eventId}?page=0&size=20

Organizer views all feedback for their event
Identifies areas for improvement
Plans better future events

Platform Quality Monitoring

GET /feedbacks/event/{eventId}?page=0&size=20

Platform admin reviews feedback
Identifies low-rated events
May influence escrow release decisions

Future Enhancements

Planned Features

1. Verified Attendee Badge

Only show "Verified Attendee" if user has booking
Increases trust in reviews
Current: Anyone can review (not implemented)

2. Average Rating Endpoint

GET /feedbacks/event/{eventId}/summary
{
  "averageRating": 4.5,
  "totalReviews": 145,
  "ratingDistribution": {
    "5": 90,
    "4": 35,
    "3": 15,
    "2": 3,
    "1": 2
  }
}

3. Helpful Votes

Users can mark reviews as helpful
Sort by most helpful
Bubble up quality reviews

4. Organizer Response

Organizers can reply to feedback
Shows engagement and care
Builds trust with future attendees

5. Escrow Integration

Average rating influences escrow release
Events <3 stars may require manual review
Automatic release for 4+ stars
Current: Not implemented

Escrow Release Logic (Future)

How Feedback May Affect Escrow

High Ratings (4-5 stars average):

✅ Automatic escrow release
Indicates successful event
No manual review needed

Medium Ratings (3-3.9 stars average):

⚠️ Manual review triggered
Platform checks for issues
May contact organizer
Usually released after review

Low Ratings (<3 stars average):

❌ Escrow release delayed
Investigation required
May require organizer explanation
Possible refunds if serious issues

Example:

Event with 4.5 average rating (90% 5-star):
→ Escrow automatically released 24 hours after event

Event with 2.8 average rating (50% 1-2 star):
→ Escrow held, manual review, contact organizer
→ Possible partial refunds if issues confirmed

Current Status: Not implemented (all events release automatically)

Best Practices

For Attendees

✅ Submit honest, constructive feedback
✅ Mention specific positives and negatives
✅ Wait until after event to review
✅ Be respectful in comments
✅ Update review if organizer addresses issues (future)

For Organizers

✅ Read all feedback carefully
✅ Identify patterns in complaints
✅ Thank reviewers for positive feedback (future)
✅ Address concerns in organizer response (future)
✅ Use feedback to improve future events

For Platform

✅ Monitor feedback quality
✅ Flag suspicious reviews
✅ Use ratings in escrow decisions (future)
✅ Display average ratings prominently
✅ Encourage verified attendee reviews (future)

Quick Reference

HTTP Status Codes

200 OK: Feedbacks retrieved successfully
201 CREATED: Feedback submitted successfully
400 BAD_REQUEST: Invalid rating value
401 UNAUTHORIZED: Not authenticated
403 FORBIDDEN: Organizer reviewing own event
404 NOT_FOUND: Event not found
409 CONFLICT: Already submitted feedback

Rating Range

Minimum: 1 star (Poor)
Maximum: 5 stars (Excellent)
Type: Integer only (no half stars)

Comment Length

Minimum: 0 (optional)
Maximum: 1000 characters
Recommended: 100-500 characters

Pagination

Default Page: 0 (first page)
Default Size: 20 items
Max Size: 100 (recommended)
Sort Order: Newest first (createdAt DESC)

Data Formats

Event ID: UUID format
User ID: UUID format
Created At: ISO 8601 timestamp (Instant)
Rating: Integer (1-5)

Integration Examples

Submit Feedback Form

const submitFeedback = async (eventId, rating, comment) => {
  const response = await fetch(`/api/v1/e-events/feedbacks/event/${eventId}`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ rating, comment })
  });
  
  if (response.status === 201) {
    alert('Thank you for your feedback!');
  } else if (response.status === 409) {
    alert('You have already reviewed this event');
  } else if (response.status === 403) {
    alert('Organizers cannot review their own events');
  }
};

Display Feedback List

const loadFeedback = async (eventId, page = 0) => {
  const response = await fetch(
    `/api/v1/e-events/feedbacks/event/${eventId}?page=${page}&size=20`
  );
  const data = await response.json();
  
  const feedbacks = data.data.content;
  const averageRating = calculateAverage(feedbacks);
  
  displayFeedbacks(feedbacks, averageRating);
};

const calculateAverage = (feedbacks) => {
  if (feedbacks.length === 0) return 0;
  const sum = feedbacks.reduce((acc, f) => acc + f.rating, 0);
  return (sum / feedbacks.length).toFixed(1);
};

Star Rating Component

const StarRating = ({ rating, onChange }) => {
  const stars = [1, 2, 3, 4, 5];
  
  return (
    <div className="star-rating">
      {stars.map(star => (
        <span
          key={star}
          className={star <= rating ? 'star filled' : 'star'}
          onClick={() => onChange(star)}
        >
          ⭐
        </span>
      ))}
    </div>
  );
};

Conclusion

The Event Feedback API provides simple yet effective review system with:

✅ 5-Star Ratings: Simple and universally understood
✅ Optional Comments: Detailed written feedback
✅ One Per User: Prevents spam and duplicate reviews
✅ Organizer Protection: Can't review own events
✅ Public Access: Anyone can view to inform decisions
✅ Pagination: Handles large numbers of reviews
✅ Future Integration: Ready for escrow release logic

Nexgate-Event-mng-Requrements

Nexgate Platform - Check-in System Architecture

NEXGATE EVENT MANAGEMENT PLATFORM

Event Management System - Requirements & User Flow Documentation

Events Management API

Ticket Management API

Event Checkout & Payment API

Event Booking Orders API

Event Check-In System API

Organizer Analytics API

Attendance Analytics API

Event Feedback API

Event Feedback API

Response Structure

EventFeedbackResponse

Paginated Response

Endpoints

1. Create Feedback

2. Get Event Feedbacks

Rating System

Star Ratings (1-5)

Average Rating Calculation

Comment Guidelines

Recommended Comment Content

Character Limit

Access Control

Who Can Submit Feedback?

Who Can View Feedback?

Use Cases

Submit Feedback After Event

View Event Reviews Before Booking

Organizer Checks Feedback

Platform Quality Monitoring

Future Enhancements

Planned Features

Escrow Release Logic (Future)

How Feedback May Affect Escrow

Best Practices

For Attendees

For Organizers

For Platform

Quick Reference

HTTP Status Codes

Rating Range

Comment Length

Pagination

Data Formats

Integration Examples

Submit Feedback Form

Display Feedback List

Star Rating Component

Conclusion