Beers API

Endpoints for searching, retrieving, and managing beer information in the database.

The Beers API provides endpoints for searching beers, retrieving detailed beer information, and managing beer data.

Endpoints

GET /api/v1/beers

Search and retrieve beers with advanced filtering options.

Query Parameters:

Parameter	Type	Description
query	string	Search term for beer name, brewery, or style
breweryId	string	Filter by brewery UUID
styleId	string	Filter by beer style UUID
productionCategory	string	Filter by production category
minProductionYear	number	Minimum production year
maxProductionYear	number	Maximum production year
minAbv	number	Minimum ABV percentage
maxAbv	number	Maximum ABV percentage
minIbu	number	Minimum IBU
maxIbu	number	Maximum IBU
page	number	Page number (default: 1)
limit	number	Results per page (default: 20, max: 100)

Response (200 OK):

JSON

{
  "success": true,
  "data": {
    "beers": [
      {
        "id": "uuid",
        "name": "Example Beer",
        "brewery": {
          "id": "uuid",
          "name": "Example Brewery"
        },
        "style": {
          "id": "uuid",
          "name": "IPA"
        },
        "abv": 6.5,
        "ibu": 60,
        "description": "A hoppy IPA",
        "imageUrl": "https://example.com/beer.jpg"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  }
}

GET /api/v1/beers/:id

Retrieve detailed information about a specific beer.

Path Parameters:

id: Beer UUID

Response (200 OK):

JSON

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Example Beer",
    "eanCode": "1234567890123",
    "brewery": {
      "id": "uuid",
      "name": "Example Brewery",
      "country": "Belgium"
    },
    "style": {
      "id": "uuid",
      "name": "Belgian Blonde",
      "category": "Ale"
    },
    "abv": 6.5,
    "ibu": 25,
    "description": "A classic Belgian blonde ale",
    "productionCategory": "commercial",
    "imageUrl": "https://example.com/beer.jpg",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Error Response (404 Not Found):

JSON

{
  "success": false,
  "error": "Beer not found",
  "code": "NOT_FOUND"
}

GET /api/v1/beers/search

Quick search for beers by name, EAN code, or brewery.

Query Parameters:

q: Search query (minimum 2 characters)

Response (200 OK):

JSON

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Example Beer",
      "brewery_name": "Example Brewery",
      "style_name": "IPA",
      "abv": 6.5
    }
  ]
}

Response Schema

Beer Object

Field	Type	Description
id	string	Unique beer identifier
name	string	Beer name
eanCode	string	EAN/UPC barcode
brewery	object	Brewery information
style	object	Beer style information
abv	number	Alcohol by volume percentage
ibu	number	International bitterness units
description	string	Beer description
productionCategory	string	Production category
imageUrl	string	Beer image URL
createdAt	string	Creation timestamp
updatedAt	string	Last update timestamp

Brewery Object

Field	Type	Description
id	string	Brewery identifier
name	string	Brewery name
country	string	Country of origin

Style Object

Field	Type	Description
id	string	Style identifier
name	string	Style name
category	string	Style category

Error Codes

Code	Description
NOT_FOUND	Beer not found
VALIDATION_ERROR	Invalid request parameters
INTERNAL_ERROR	Server error

Next Steps

Collection API - Add beers to your collection
Ratings API - Rate and review beers
Authentication API - User authentication