Ratings API

Endpoints for rating beers, managing reviews, and retrieving tasting notes and ratings data.

The Ratings API allows users to rate and review beers, track their tasting experiences, and retrieve rating statistics.

Endpoints

GET /api/v1/ratings

Retrieve ratings with optional filtering.

Query Parameters:

Parameter	Type	Description
beerId	string	Get ratings for specific beer
userId	string	Get ratings by specific user
ratingId	string	Get specific rating by ID
includeAnalysis	boolean	Include production analysis
limit	number	Results per page (default: 20)
offset	number	Pagination offset
sort	string	Sort field (created_at, rating, etc.)
order	string	Sort order (ASC, DESC)

Response (200 OK):

JSON

{
  "success": true,
  "data": {
    "ratings": [
      {
        "id": "uuid",
        "beerId": "uuid",
        "beerName": "Example Beer",
        "userId": "uuid",
        "username": "beerfan",
        "rating": 4.5,
        "aroma": 4,
        "appearance": 4,
        "taste": 5,
        "palate": 4,
        "overall": 4.5,
        "tastingNotes": {
          "aromaNotes": ["Citrus", "Pine"],
          "appearanceNotes": ["Clear", "Golden"],
          "tasteNotes": ["Hop forward", "Bitter finish"],
          "palateNotes": ["Medium body", "Good carbonation"]
        },
        "reviewText": "Excellent IPA with great hop character",
        "productionDateCategory": "fresh",
        "createdAt": "2024-01-15T10:00:00Z"
      }
    ],
    "pagination": {
      "total": 45,
      "limit": 20,
      "offset": 0
    }
  }
}

POST /api/v1/ratings

Create a new beer rating.

Request Body:

JSON

{
  "beerId": "uuid",
  "rating": 4.5,
  "aroma": 4,
  "appearance": 4,
  "taste": 5,
  "palate": 4,
  "overall": 4.5,
  "tastingNotes": {
    "aromaNotes": ["Citrus", "Pine"],
    "appearanceNotes": ["Clear", "Golden"],
    "tasteNotes": ["Hop forward", "Bitter finish"],
    "palateNotes": ["Medium body", "Good carbonation"]
  },
  "reviewText": "Excellent IPA with great hop character",
  "consumedDate": "2024-01-15"
}

Response (201 Created):

JSON

{
  "success": true,
  "data": {
    "id": "uuid",
    "beerId": "uuid",
    "rating": 4.5,
    "productionDateCategory": "fresh",
    "createdAt": "2024-01-15T10:00:00Z"
  },
  "message": "Rating created successfully"
}

GET /api/v1/ratings/:beerId

Get all ratings for a specific beer.

Path Parameters:

beerId: Beer UUID

Response (200 OK):

JSON

{
  "success": true,
  "data": {
    "beer": {
      "id": "uuid",
      "name": "Example Beer",
      "brewery": "Example Brewery"
    },
    "ratings": [
      {
        "id": "uuid",
        "userId": "uuid",
        "username": "beerfan",
        "rating": 4.5,
        "tastingNotes": {
          "aromaNotes": ["Citrus"],
          "tasteNotes": ["Hop forward"]
        },
        "reviewText": "Great beer!",
        "createdAt": "2024-01-15T10:00:00Z"
      }
    ],
    "stats": {
      "averageRating": 4.2,
      "totalRatings": 15,
      "ratingDistribution": {
        "5": 5,
        "4": 7,
        "3": 2,
        "2": 1,
        "1": 0
      }
    }
  }
}

PUT /api/v1/ratings/:id

Update an existing rating.

Path Parameters:

id: Rating UUID

Request Body:

JSON

{
  "rating": 4.8,
  "reviewText": "Updated review with more details",
  "tastingNotes": {
    "aromaNotes": ["Citrus", "Pine", "Tropical"],
    "tasteNotes": ["Very hop forward", "Long bitter finish"]
  }
}

Response (200 OK):

JSON

{
  "success": true,
  "data": {
    "id": "uuid",
    "rating": 4.8,
    "reviewText": "Updated review with more details",
    "updatedAt": "2024-01-16T10:00:00Z"
  },
  "message": "Rating updated successfully"
}

Rating Scale

All rating fields use a 1-5 scale:

1 - Poor
2 - Below Average
3 - Average
4 - Good
5 - Excellent

Tasting Notes Schema

Aroma Notes

Common descriptors: Citrus, Pine, Tropical, Floral, Herbal, Caramel, Chocolate, Coffee, etc.

Appearance Notes

Common descriptors: Clear, Hazy, Golden, Amber, Dark, White head, Rocky head, etc.

Taste Notes

Common descriptors: Hop forward, Malt forward, Bitter, Sweet, Sour, Fruity, Roasty, etc.

Palate Notes

Common descriptors: Light body, Medium body, Full body, Carbonated, Flat, Creamy, etc.

Production Date Categories

fresh - Consumed within 3 months of production
aged - Consumed 3-12 months after production
mature - Consumed more than 12 months after production

Error Codes

Code	Description
VALIDATION_ERROR	Invalid rating data
NOT_FOUND	Rating or beer not found
UNAUTHORIZED	User not authorized
DUPLICATE_RATING	User already rated this beer

Next Steps

Beers API - Find beers to rate
Collection API - Track consumption for ratings
Authentication API - User authentication