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:

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:

  1. Validates user is authenticated
  2. Validates event exists
  3. Checks user is NOT the event organizer
  4. Checks user hasn't already submitted feedback
  5. Creates feedback record
  6. Returns created feedback

Validation Rules:

Standard Error Types:

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:

Pagination Details:

Standard Error Types:

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

Recommended Comment Content

Good Comments Include:

Example Good Comments:

"Amazing event! The keynote speakers were excellent and provided valuable insights. 
The venue was perfect and well-organized. Only suggestion would be to have longer 
lunch breaks. Will definitely attend next year!"

"Great networking opportunities and diverse range of topics. Sound system could 
be improved in the main hall."

"Well organized but sessions felt rushed. Would prefer fewer sessions with more 
time for Q&A."

Avoid:

Character Limit

Access Control

Who Can Submit Feedback?

Allowed:

Not Allowed:

Future Restriction (Recommended):

Who Can View Feedback?

Anyone (Public access):

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

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

4. Organizer Response

5. Escrow Integration

Escrow Release Logic (Future)

How Feedback May Affect Escrow

High Ratings (4-5 stars average):

Medium Ratings (3-3.9 stars average):

Low Ratings (<3 stars average):

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

Rating Range

Comment Length

Pagination

Data Formats

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

Revision #1
Created 11 December 2025 10:24:47 by Admin Qbit
Updated 11 December 2025 10:25:46 by Admin Qbit