# Service Professional Ratings API - Quick Reference ## Base URL ``` /api/v1/ratings ``` ## Authentication Most endpoints require JWT Bearer token: ``` Authorization: Bearer ``` --- ## Endpoints Summary | Method | Endpoint | Auth | Description | |--------|----------|------|-------------| | POST | `/` | ✅ | Create rating | | GET | `/{rating_id}` | ❌ | Get rating by ID | | PUT | `/{rating_id}` | ✅ | Update rating | | DELETE | `/{rating_id}` | ✅ | Delete rating | | POST | `/list` | ❌ | List ratings with filters | | GET | `/stats/{professional_id}` | ❌ | Get rating statistics | | POST | `/{rating_id}/responses` | ✅ | Add response to rating | | POST | `/{rating_id}/helpful` | ❌ | Mark rating as helpful | --- ## 1. Create Rating **POST** `/api/v1/ratings/` Create a new rating for a service professional after order completion. ### Request ```json { "order_id": "550e8400-e29b-41d4-a716-446655440000", "service_professional_id": "prof_123", "service_id": "svc_456", "rating_score": 4.5, "review_title": "Excellent service!", "review_text": "Very professional and skilled. Highly recommend!", "is_anonymous": false } ``` ### Response (201) ```json { "rating_id": "660e8400-e29b-41d4-a716-446655440001", "order_id": "550e8400-e29b-41d4-a716-446655440000", "service_professional_id": "prof_123", "customer_id": "cust_456", "merchant_id": "merchant_789", "service_id": "svc_456", "rating_score": 4.5, "review_title": "Excellent service!", "review_text": "Very professional and skilled. Highly recommend!", "is_verified_purchase": true, "is_anonymous": false, "helpful_count": 0, "status": "active", "created_at": "2024-02-27T10:30:00", "updated_at": "2024-02-27T10:30:00", "responses": [] } ``` ### Notes - Rating score must be 1.0-5.0 in 0.5 increments (1.0, 1.5, 2.0, etc.) - Customer ID extracted from JWT token - Prevents duplicate ratings for same order/professional - Order must exist and be completed --- ## 2. Get Rating by ID **GET** `/api/v1/ratings/{rating_id}` Retrieve a specific rating with all responses. ### Response (200) ```json { "rating_id": "660e8400-e29b-41d4-a716-446655440001", "order_id": "550e8400-e29b-41d4-a716-446655440000", "service_professional_id": "prof_123", "customer_id": "cust_456", "rating_score": 4.5, "review_title": "Excellent service!", "review_text": "Very professional and skilled.", "is_verified_purchase": true, "is_anonymous": false, "helpful_count": 5, "status": "active", "created_at": "2024-02-27T10:30:00", "updated_at": "2024-02-27T10:30:00", "responses": [ { "response_id": "770e8400-e29b-41d4-a716-446655440002", "rating_id": "660e8400-e29b-41d4-a716-446655440001", "responder_id": "prof_123", "responder_type": "professional", "response_text": "Thank you for your feedback!", "created_at": "2024-02-27T11:00:00", "updated_at": "2024-02-27T11:00:00" } ] } ``` --- ## 3. Update Rating **PUT** `/api/v1/ratings/{rating_id}` Update an existing rating (only by customer who created it). ### Request ```json { "rating_score": 5.0, "review_text": "Updated review - even better than I thought!", "review_title": "Outstanding!" } ``` ### Response (200) Same as Get Rating response with updated fields. ### Notes - Only the customer who created the rating can update it - All fields are optional - Cannot change order_id or service_professional_id --- ## 4. Delete Rating **DELETE** `/api/v1/ratings/{rating_id}` Soft delete a rating (sets status to 'deleted'). ### Response (204) No content ### Notes - Only the customer who created the rating can delete it - Soft delete - data remains in database with status='deleted' - Deleted ratings don't appear in public lists --- ## 5. List Ratings **POST** `/api/v1/ratings/list` List ratings with filters and pagination. ### Request ```json { "service_professional_id": "prof_123", "min_rating": 4.0, "max_rating": 5.0, "status": "active", "limit": 20, "offset": 0 } ``` ### Response (200) ```json { "ratings": [ { "rating_id": "660e8400-e29b-41d4-a716-446655440001", "service_professional_id": "prof_123", "rating_score": 4.5, "review_title": "Excellent service!", "review_text": "Very professional and skilled.", "helpful_count": 5, "status": "active", "created_at": "2024-02-27T10:30:00", "responses": [] } ], "pagination": { "limit": 20, "offset": 0, "total": 150 } } ``` ### Filter Options - `service_professional_id` - Filter by professional - `customer_id` - Filter by customer - `merchant_id` - Filter by merchant - `service_id` - Filter by service - `min_rating` - Minimum rating score (1.0-5.0) - `max_rating` - Maximum rating score (1.0-5.0) - `status` - Filter by status (defaults to 'active') - `limit` - Results per page (1-100, default 20) - `offset` - Pagination offset (default 0) --- ## 6. Get Rating Statistics **GET** `/api/v1/ratings/stats/{service_professional_id}` Get aggregated rating statistics for a service professional. ### Response (200) ```json { "service_professional_id": "prof_123", "total_ratings": 150, "average_rating": 4.3, "rating_distribution": { "5": 80, "4": 45, "3": 15, "2": 7, "1": 3 }, "verified_purchase_count": 145, "total_reviews_with_text": 120 } ``` ### Notes - Only includes active ratings - Average rating rounded to 2 decimal places - Distribution shows count per star rating (1-5) - Useful for displaying professional profiles --- ## 7. Create Response to Rating **POST** `/api/v1/ratings/{rating_id}/responses` Service professional, merchant, or admin can respond to a rating. ### Request ```json { "response_text": "Thank you for your feedback! We're glad you enjoyed our service and look forward to serving you again." } ``` ### Response (201) ```json { "response_id": "770e8400-e29b-41d4-a716-446655440002", "rating_id": "660e8400-e29b-41d4-a716-446655440001", "responder_id": "prof_123", "responder_type": "professional", "response_text": "Thank you for your feedback!", "created_at": "2024-02-27T11:00:00", "updated_at": "2024-02-27T11:00:00" } ``` ### Authorization Rules - **Professional**: Can respond to their own ratings - **Merchant**: Can respond to ratings in their establishment - **Admin**: Can respond to any rating ### Notes - Response text must be 10-1000 characters - Multiple responses allowed per rating - Responder type determined from JWT role --- ## 8. Mark Rating as Helpful **POST** `/api/v1/ratings/{rating_id}/helpful` Increment the helpful count for a rating. ### Response (200) Returns the updated rating with incremented `helpful_count`. ### Notes - No authentication required - Can be called multiple times (no duplicate prevention) - Consider implementing client-side tracking to prevent abuse --- ## Error Responses ### 400 Bad Request ```json { "detail": "Rating already exists for this order and professional" } ``` ### 401 Unauthorized ```json { "detail": "Not authenticated" } ``` ### 403 Forbidden ```json { "detail": "Not authorized to update this rating" } ``` ### 404 Not Found ```json { "detail": "Rating not found" } ``` ### 500 Internal Server Error ```json { "detail": "Failed to create rating: " } ``` --- ## Common Use Cases ### Display Professional Profile with Ratings 1. GET `/api/v1/ratings/stats/{professional_id}` - Get overall stats 2. POST `/api/v1/ratings/list` with filters - Get recent reviews ### Customer Leaves Review After Service 1. POST `/api/v1/ratings/` - Create rating 2. Customer receives confirmation ### Professional Responds to Review 1. GET `/api/v1/ratings/{rating_id}` - View rating 2. POST `/api/v1/ratings/{rating_id}/responses` - Add response ### Browse All Reviews for a Professional 1. POST `/api/v1/ratings/list` with `service_professional_id` filter 2. Paginate through results --- ## Rate Limiting Recommendations Consider implementing rate limits: - Rating creation: 5 per hour per customer - Helpful marking: 20 per hour per IP - Response creation: 10 per hour per professional - List queries: 100 per minute per IP --- ## Testing with cURL ### Create Rating ```bash curl -X POST "http://localhost:8000/api/v1/ratings/" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "order_id": "550e8400-e29b-41d4-a716-446655440000", "service_professional_id": "prof_123", "rating_score": 4.5, "review_title": "Great service!", "review_text": "Highly recommend!" }' ``` ### Get Statistics ```bash curl -X GET "http://localhost:8000/api/v1/ratings/stats/prof_123" ``` ### List Ratings ```bash curl -X POST "http://localhost:8000/api/v1/ratings/list" \ -H "Content-Type: application/json" \ -d '{ "service_professional_id": "prof_123", "limit": 10 }' ``` --- **Last Updated**: February 27, 2024