Collection API

Endpoints for managing your personal beer collection, including adding, updating, and tracking consumption.

The Collection API allows users to manage their personal beer collection, track inventory, and log consumption events.

Endpoints

GET /api/v1/collection

Retrieve the user’s beer collection with optional filtering.

Query Parameters:

Parameter	Type	Description
beerId	string	Filter by specific beer UUID
styleId	string	Filter by beer style UUID
breweryId	string	Filter by brewery UUID
hasPhotos	boolean	Show only items with photos
showConsumed	boolean	Include consumed items
nearingBBD	boolean	Show items nearing best before date
pastBBD	boolean	Show items past best before date
containerType	string	Filter by container type (bottle, can, keg, growler, other)
includeMetadata	boolean	Include collection statistics
page	number	Page number
limit	number	Items per page

Response (200 OK):

JSON

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "beer": {
        "id": "uuid",
        "name": "Example Beer",
        "brewery": "Example Brewery",
        "style": "IPA"
      },
      "quantity": 2,
      "acquisitionDate": "2024-01-15",
      "bestBeforeDate": "2025-01-15",
      "storageLocation": "Cellar",
      "containerType": "bottle",
      "containerSizeMl": 330,
      "notes": "Great condition",
      "photoUrls": ["https://example.com/photo1.jpg"],
      "isConsumed": false
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45
  }
}

POST /api/v1/collection

Add a new item to the collection.

Request Body (for existing beer):

JSON

{
  "beerId": "uuid",
  "quantity": 2,
  "acquisitionDate": "2024-01-15",
  "productionDate": "2023-12-01",
  "bestBeforeDate": "2025-01-15",
  "storageLocation": "Cellar",
  "notes": "Excellent condition",
  "photoUrls": ["https://example.com/photo.jpg"],
  "containerType": "bottle",
  "containerSizeMl": 330
}

Request Body (for new beer):

JSON

{
  "name": "New Beer",
  "breweryId": "uuid",
  "styleId": "uuid",
  "abv": 5.5,
  "quantity": 1,
  "acquisitionDate": "2024-01-15",
  "containerType": "can"
}

Response (201 Created):

JSON

{
  "success": true,
  "data": {
    "id": "uuid",
    "beer": {
      "id": "uuid",
      "name": "Example Beer"
    },
    "quantity": 2,
    "acquisitionDate": "2024-01-15",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

PUT /api/v1/collection/:id

Update an existing collection item.

Path Parameters:

id: Collection item UUID

Request Body:

JSON

{
  "quantity": 3,
  "storageLocation": "Refrigerator",
  "notes": "Updated notes",
  "bestBeforeDate": "2025-02-15"
}

Response (200 OK):

JSON

{
  "success": true,
  "data": {
    "id": "uuid",
    "quantity": 3,
    "storageLocation": "Refrigerator",
    "notes": "Updated notes",
    "updatedAt": "2024-01-16T10:00:00Z"
  }
}

DELETE /api/v1/collection/:id

Remove an item from the collection.

Path Parameters:

id: Collection item UUID

Response (200 OK):

JSON

{
  "success": true,
  "message": "Item removed from collection successfully"
}

POST /api/v1/collection/:id/consume

Log consumption of a collection item.

Path Parameters:

id: Collection item UUID

Request Body:

JSON

{
  "quantity": 1,
  "consumedDate": "2024-01-16",
  "notes": "Enjoyed with friends",
  "ratingId": "uuid"
}

Response (200 OK):

JSON

{
  "success": true,
  "data": {
    "event": {
      "id": "uuid",
      "quantity": 1,
      "consumedDate": "2024-01-16",
      "notes": "Enjoyed with friends"
    },
    "fullyConsumed": false,
    "remainingQuantity": 1
  }
}

Collection Item Schema

Field	Type	Description
id	string	Collection item identifier
beer	object	Beer information
quantity	number	Current quantity
acquisitionDate	string	Date acquired (YYYY-MM-DD)
productionDate	string	Beer production date
bestBeforeDate	string	Best before date
storageLocation	string	Storage location
containerType	string	Container type
containerSizeMl	number	Container size in ml
notes	string	Additional notes
photoUrls	array	Array of photo URLs
isConsumed	boolean	Whether item is fully consumed
createdAt	string	Creation timestamp
updatedAt	string	Last update timestamp

Container Types

bottle - Glass bottle
can - Aluminum can
keg - Keg
growler - Growler
other - Other container type

Error Codes

Code	Description
VALIDATION_ERROR	Invalid request data
NOT_FOUND	Collection item not found
UNAUTHORIZED	User not authorized
INSUFFICIENT_QUANTITY	Not enough items to consume

Next Steps

Beers API - Search for beers to add to collection
Ratings API - Rate beers you’ve consumed
Marketplace API - Buy and sell beers