Reviews API

The Reviews API allows users to add, view, and delete reviews for waypoints (water fountains).

Endpoints

GET /api/reviews

Get reviews with optional filtering.

Authentication: Not required

Query Parameters:

userId (string, optional) - Filter reviews by user ID
bubblerId (number, optional) - Filter reviews by waypoint ID

Example Requests:

Get all reviews:

curl https://bubblymaps.org/api/reviews

Get reviews by a specific user:

curl "https://bubblymaps.org/api/reviews?userId=user123"

Get reviews for a specific waypoint:

curl "https://bubblymaps.org/api/reviews?bubblerId=42"

Response:

{
  "reviews": [
    {
      "id": 1,
      "bubblerId": 42,
      "userId": "user123",
      "rating": 5,
      "comment": "Great fountain! Clean water and easy to access.",
      "createdAt": "2024-01-20T16:30:00Z",
      "updatedAt": "2024-01-20T16:30:00Z"
    },
    {
      "id": 2,
      "bubblerId": 42,
      "userId": "user456",
      "rating": 4,
      "comment": "Good location but gets crowded.",
      "createdAt": "2024-01-21T09:15:00Z",
      "updatedAt": "2024-01-21T09:15:00Z"
    }
  ]
}

POST /api/reviews

Create a new review for a waypoint.

Authentication: Required (Session)

Request Body:

{
  "bubblerId": 42,
  "rating": 5,
  "comment": "Excellent fountain with cold, clean water!"
}

Required Fields:

bubblerId (number) - ID of the waypoint being reviewed
rating (number) - Rating value (typically 1-5)

Optional Fields:

comment (string) - Text review comment

Example Request:

curl -X POST https://bubblymaps.org/api/reviews \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_COOKIE" \
  -d '{
    "bubblerId": 42,
    "rating": 5,
    "comment": "Excellent fountain with cold, clean water!"
  }'

Response (201 Created):

{
  "review": {
    "id": 15,
    "bubblerId": 42,
    "userId": "user789",
    "rating": 5,
    "comment": "Excellent fountain with cold, clean water!",
    "createdAt": "2024-01-22T14:20:00Z",
    "updatedAt": "2024-01-22T14:20:00Z"
  }
}

XP Rewards:

Users are awarded XP (experience points) for adding reviews.

Error Responses:

401 Unauthorized - User not authenticated
400 Bad Request - Missing required fields
500 Internal Server Error - Failed to create review

DELETE /api/reviews

Delete a review.

Authentication: Required (Session, API Token, or Moderator)

Query Parameters:

id (number, required) - ID of the review to delete

Authorization Rules:

Reviews can be deleted by:

The user who created the review
Users with moderator privileges
API token holders

Example Request:

curl -X DELETE "https://bubblymaps.org/api/reviews?id=15" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "review": {
    "id": 15,
    "bubblerId": 42,
    "userId": "user789",
    "rating": 5,
    "comment": "Excellent fountain with cold, clean water!",
    "createdAt": "2024-01-22T14:20:00Z",
    "updatedAt": "2024-01-22T14:20:00Z"
  }
}

Error Responses:

401 Unauthorized - User not authenticated
403 Forbidden - User not authorized to delete this review
400 Bad Request - Missing review ID
404 Not Found - Review does not exist
500 Internal Server Error - Failed to delete review

Data Model

Review Object

Field	Type	Description
`id`	number	Unique identifier
`bubblerId`	number	ID of the waypoint being reviewed
`userId`	string	ID of the user who wrote the review
`rating`	number	Numerical rating
`comment`	string	Text review comment (optional)
`createdAt`	string	Creation timestamp (ISO 8601)
`updatedAt`	string	Last update timestamp (ISO 8601)

Usage Examples

JavaScript/Fetch - Add a Review

async function addReview(bubblerId, rating, comment) {
  const response = await fetch('https://bubblymaps.org/api/reviews', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    credentials: 'include', // Include session cookie
    body: JSON.stringify({
      bubblerId,
      rating,
      comment
    })
  });
  
  if (!response.ok) {
    throw new Error('Failed to add review');
  }
  
  return await response.json();
}

// Usage
addReview(42, 5, 'Great fountain!')
  .then(data => console.log('Review added:', data))
  .catch(error => console.error('Error:', error));

Python - Get Reviews for a Waypoint

import requests

def get_waypoint_reviews(bubbler_id):
    url = f"https://bubblymaps.org/api/reviews?bubblerId={bubbler_id}"
    response = requests.get(url)
    
    if response.status_code == 200:
        return response.json()['reviews']
    else:
        raise Exception(f"Failed to fetch reviews: {response.status_code}")

# Usage
reviews = get_waypoint_reviews(42)
for review in reviews:
    print(f"Rating: {review['rating']}/5 - {review['comment']}")

Reviews API

On this page