TAPPr API Documentation

Welcome to the TAPPr API documentation. This API allows you to interact with beer data for your homebrewing needs.

UUID System

The TAPPr API uses two UUID fields for brews (beers):

  • api_brew_uuid: A UUID generated by the API that serves as the unique immutable key for the record in the database.
  • brewUuid: A UUID provided by the companion app that serves as a reference for the app.

When creating a new brew, you can provide a brewUuid from the companion app. The API will generate a new api_brew_uuid for the brew and return both UUIDs in the response. Reviews reference brews using the api_brew_uuid field.

Endpoints

Get All Brews

GET /api/beers

Returns a list of all brews (beers).

[
  {
    "id": 1,
    "name": "Hoppy IPA",
    "style": "India Pale Ale",
    "abv": 6.5
  }
]

Get Brew by ID

GET /api/beers/{id}

Returns a specific brew (beer) by ID.

{
  "id": 1,
  "name": "Hoppy IPA",
  "style": "India Pale Ale",
  "abv": 6.5,
  "ibu": 65.5,
  "description": "A hoppy IPA with citrus and pine notes",
  "brewDate": "2023-10-15",
  "kegLevel": 85,
  "brewUuid": "550e8400-e29b-41d4-a716-446655440000",
  "api_brew_uuid": "7dfb14c4-d288-4b1e-ae69-ec2d733aa434"
}

Get Brew by API UUID

GET /api/beers/api/{apiBrewUuid}

Returns a specific brew (beer) by its API-generated UUID.

{
  "id": 1,
  "name": "Hoppy IPA",
  "style": "India Pale Ale",
  "abv": 6.5,
  "ibu": 65.5,
  "description": "A hoppy IPA with citrus and pine notes",
  "brewDate": "2023-10-15",
  "kegLevel": 85,
  "brewUuid": "550e8400-e29b-41d4-a716-446655440000",
  "api_brew_uuid": "7dfb14c4-d288-4b1e-ae69-ec2d733aa434"
}

Add New Brew

POST /api/beers/add

Adds a new brew (beer) to the system.

Request Body:

{
  "name": "New Brew",
  "style": "IPA",
  "abv": 5.5,
  "ibu": 40.5,
  "description": "Description of the brew",
  "brewDate": "2024-04-01",
  "kegLevel": 100,
  "brewUuid": "550e8400-e29b-41d4-a716-446655440001"
}

Response:

{
  "message": "Brew added successfully",
  "brew": {
    "id": 4,
    "name": "New Brew",
    "style": "IPA",
    "abv": 5.5,
    "ibu": 40.5,
    "description": "Description of the brew",
    "brewDate": "2024-04-01",
    "kegLevel": 100,
    "brewUuid": "550e8400-e29b-41d4-a716-446655440001",
    "api_brew_uuid": "7dfb14c4-d288-4b1e-ae69-ec2d733aa434",
    "createdAt": "2024-04-15T14:30:00Z",
    "updatedAt": "2024-04-15T14:30:00Z"
  }
}

Update Brew

PATCH /api/beers/{id}/update

Updates an existing brew (beer).

Request Body:

{
  "name": "Updated Beer Name",
  "kegLevel": 75
}

Response:

{
  "message": "Brew updated successfully",
  "brew": {
    "id": 1,
    "name": "Updated Brew Name",
    "style": "India Pale Ale",
    "abv": 6.5,
    "ibu": 65.5,
    "description": "A hoppy IPA with citrus and pine notes",
    "brewDate": "2023-10-15",
    "kegLevel": 75,
    "brewUuid": "550e8400-e29b-41d4-a716-446655440000",
    "api_brew_uuid": "7dfb14c4-d288-4b1e-ae69-ec2d733aa434",
    "createdAt": "2023-11-15T14:30:00Z",
    "updatedAt": "2024-04-15T14:30:00Z"
  }
}

Delete Brew

DELETE /api/beers/{id}/delete

Deletes a brew (beer) from the system.

Response:

{
  "message": "Brew deleted successfully"
}

Review Endpoints

Get All Reviews

GET /api/reviews

Returns a list of all reviews.

Get Review by ID

GET /api/reviews/{id}

Returns a specific review by ID.

Get Reviews by API Brew UUID

GET /api/reviews/api-brew/{apiBrewUuid}

Returns all reviews for a specific brew using the API-generated UUID (primary reference).

Get Reviews by Companion App Brew UUID

GET /api/reviews/brew/{brewUuid}

Returns all reviews for a specific brew using the companion app UUID (for backward compatibility).

Add Quick Review

POST /api/reviews/add

Adds a new quick review.

Request Body:

{
  "api_brew_uuid": "7dfb14c4-d288-4b1e-ae69-ec2d733aa434",
  "brewUuid": "550e8400-e29b-41d4-a716-446655440000",
  "reviewerName": "John Doe",
  "isAnonymous": false,
  "reviewType": "quick",
  "quickReview": {
    "overallRating": 4,
    "comments": "Great IPA, would drink again!"
  }
}

Response:

{
  "message": "Review added successfully",
  "review": {
    "id": 1,
    "reviewId": "550e8400-e29b-41d4-a716-446655440002",
    "api_brew_uuid": "7dfb14c4-d288-4b1e-ae69-ec2d733aa434",
    "brewUuid": "550e8400-e29b-41d4-a716-446655440000",
    "reviewerName": "John Doe",
    "isAnonymous": false,
    "reviewDate": "2023-11-15T14:30:00Z",
    "reviewType": "quick",
    "quickReview": {
      "overallRating": 4,
      "comments": "Great IPA, would drink again!"
    },
    "createdAt": "2023-11-15T14:30:00Z",
    "updatedAt": "2023-11-15T14:30:00Z"
  }
}

Add Standard Review

POST /api/reviews/add

Adds a new standard review with more detailed ratings.

Request Body:

{
  "api_brew_uuid": "7dfb14c4-d288-4b1e-ae69-ec2d733aa434",
  "brewUuid": "550e8400-e29b-41d4-a716-446655440000",
  "reviewerName": "Jane Smith",
  "isAnonymous": false,
  "reviewType": "standard",
  "quickReview": {
    "overallRating": 4,
    "comments": "Great IPA, would drink again!"
  },
  "standardReview": {
    "appearance": 4,
    "aroma": 5,
    "taste": 4,
    "mouthfeel": 3,
    "comments": "Nice golden color, strong hop aroma, good balance of flavors"
  }
}

Add Expert Review

POST /api/reviews/add

Adds a new expert review with comprehensive ratings.

Request Body:

{
  "api_brew_uuid": "7dfb14c4-d288-4b1e-ae69-ec2d733aa434",
  "brewUuid": "550e8400-e29b-41d4-a716-446655440000",
  "reviewerId": "123e4567-e89b-12d3-a456-426614174000",
  "isAnonymous": false,
  "reviewType": "expert",
  "quickReview": {
    "overallRating": 4,
    "comments": "Great IPA, would drink again!"
  },
  "standardReview": {
    "appearance": 4,
    "aroma": 5,
    "taste": 4,
    "mouthfeel": 3,
    "comments": "Nice golden color, strong hop aroma, good balance of flavors"
  },
  "expertReview": {
    "appearance": {
      "clarity": 4,
      "color": 5,
      "head": 4,
      "notes": "Golden amber with excellent head retention"
    },
    "aroma": {
      "intensity": 4,
      "maltiness": 3,
      "hoppiness": 5,
      "fruitiness": 4,
      "otherAromatics": 3,
      "notes": "Strong citrus and pine hop aroma with supporting malt backbone"
    },
    "taste": {
      "flavorIntensity": 4,
      "maltCharacter": 3,
      "hopCharacter": 5,
      "bitterness": 4,
      "sweetness": 2,
      "balance": 4,
      "notes": "Bold hop flavor with enough malt to support, clean bitterness"
    },
    "mouthfeel": {
      "body": 3,
      "carbonation": 4,
      "warmth": 2,
      "creaminess": 3,
      "notes": "Medium body with lively carbonation"
    },
    "aftertaste": {
      "duration": 4,
      "pleasantness": 4,
      "notes": "Pleasant lingering hop bitterness"
    },
    "styleAccuracy": 9
  }
}

Update Review

PATCH /api/reviews/{id}/update

Updates an existing review.

Delete Review

DELETE /api/reviews/{id}/delete

Deletes a review from the system.

Response:

{
  "message": "Review deleted successfully"
}

Authentication

The API is protected with an API key. You must include the API key in the header of each request.

API Key Authentication

Include the API key in the X_API_Key header of your requests.Note: Use underscore (_) instead of dash (-) in the header name.

// Example using fetch
fetch('https://tappr.beer/api/beers', {
  headers: {
    'X_API_Key': 'your-api-key-here'
  }
})
// Example using axios
axios.get('https://tappr.beer/api/beers', {
  headers: {
    'X_API_Key': 'your-api-key-here'
  }
})
// Example using curl
curl -X GET   -H "X_API_Key: your-api-key-here"   https://tappr.beer/api/beers
← Back to Home