Bartendie GraphQL API Guide

Bartendie GraphQL API Guide

Overview

Bartendie now provides a comprehensive GraphQL API for managing your home bar. The GraphQL API replaces the REST endpoints and provides a more flexible, efficient way to interact with the system.

Endpoints

GraphQL API

• POST /api/graphql - Main GraphQL endpoint for queries and mutations
• GET/POST /api/graphiql - GraphiQL interface for development (dev mode only)

Legacy REST (Deprecated)

• GET /api/health - Health check
• GET /api/info - API information
• GET /api/events - List events (use GraphQL instead)
• POST /api/events - Create event (use GraphQL instead)

GraphQL Features

Domain Coverage

• Events - Cocktail events, themes, guest lists, menus
• Venues - Locations, bars, equipment, setup
• Recipes - Cocktail recipes, ingredients, instructions
• Inventory - Stock management, products, shopping lists

Query Capabilities

• Flexible field selection
• Nested data fetching
• Filtering and arguments
• Real-time data

Mutation Support

• Create, update, delete operations
• CQRS/Event Sourcing integration
• Validation and error handling

Example Queries

System Information

{
  health {
    status
    timestamp
  }

  apiInfo {
    app
    version
    description
    status
  }
}

Events

# List all events
{
  events {
    id
    name
    description
    date
    expectedGuestCount
    status
    venue {
      name
      capacity
    }
    theme {
      name
      colorScheme
    }
  }
}

# Get specific event
{
  event(id: "event-123") {
    id
    name
    description
    guests {
      name
      rsvpStatus
      drinkPreferences
    }
    menu {
      name
      recipes {
        name
        difficulty
        ingredients {
          ingredientName
          amount
          unit
        }
      }
    }
  }
}

Recipes

# List recipes with filtering
{
  recipes(category: CLASSIC, difficulty: BEGINNER) {
    id
    name
    description
    category
    difficulty
    prepTimeMinutes
    instructions
    garnish
    glassware
    tags
    ingredients {
      ingredientName
      amount
      unit
      optional
    }
    estimatedCost
    nutrition {
      caloriesPerServing
      alcoholByVolume
    }
  }
}

Venues

# List venues with bars
{
  venues {
    id
    name
    description
    venueType
    capacity
    bars {
      id
      name
      barType
      features
      equipment {
        name
        equipmentType
        condition
      }
    }
  }
}

Inventory

# List inventory with low stock filter
{
  inventory(lowStockOnly: true) {
    id
    name
    brand
    productType
    currentLevel
    minimumLevel
    unit
    isLowStock
    expirationDate
    location
    product {
      description
      alcoholContent
      manufacturer
    }
  }
}

Example Mutations

Create Event

mutation {
  createEvent(input: {
    name: "Holiday Party"
    description: "Annual holiday celebration"
    date: "2024-12-25"
    expectedGuestCount: 50
    venueId: "venue-1"
  }) {
    id
    name
    description
    status
    createdAt
  }
}

Create Recipe

mutation {
  createRecipe(input: {
    name: "Perfect Old Fashioned"
    description: "Classic whiskey cocktail with a modern twist"
    category: CLASSIC
    difficulty: INTERMEDIATE
    prepTimeMinutes: 5
    servings: 1
    instructions: [
      "Add sugar cube to glass"
      "Add 2-3 dashes of bitters"
      "Muddle sugar and bitters"
      "Add whiskey and large ice cube"
      "Stir gently for 30 seconds"
      "Express orange peel oils and garnish"
    ]
    garnish: "Orange peel"
    glassware: "Old fashioned glass"
    tags: ["whiskey", "classic", "stirred"]
    ingredients: [
      {
        ingredientName: "Bourbon Whiskey"
        amount: 2
        unit: OZ
        ingredientType: SPIRIT
      }
      {
        ingredientName: "Simple Syrup"
        amount: 0.25
        unit: OZ
        ingredientType: SYRUP
      }
      {
        ingredientName: "Angostura Bitters"
        amount: 2
        unit: DASH
        ingredientType: BITTERS
      }
    ]
  }) {
    id
    name
    category
    difficulty
    estimatedCost
  }
}

Add Inventory Item

mutation {
  addInventoryItem(input: {
    name: "Premium Bourbon"
    brand: "Buffalo Trace"
    productType: SPIRIT
    currentLevel: 750
    unit: ML
    minimumLevel: 200
    costPerUnit: 0.05
    location: "Main Bar"
    barcode: "123456789"
  }) {
    id
    name
    currentLevel
    isLowStock
  }
}

Create Venue with Bar

mutation {
  createVenue(input: {
    name: "Home Bar Setup"
    description: "Main entertaining area"
    venueType: HOME
    capacity: 20
    amenities: ["Full bar", "Sound system", "Outdoor access"]
  }) {
    id
    name
    venueType
  }
}

# Then add a bar to the venue
mutation {
  addBarToVenue(
    venueId: "venue-123"
    input: {
      name: "Main Bar"
      description: "Primary cocktail preparation area"
      barType: FULL_SERVICE
      capacity: 15
      features: ["Ice machine", "Wine storage", "Premium spirits"]
    }
  ) {
    id
    name
    bars {
      name
      barType
      features
    }
  }
}

GraphQL Schema Features

Type System

• Scalars: String, Int, Float, Boolean, ID, Date, DateTime
• Objects: Event, Venue, Recipe, Ingredient, InventoryItem, etc.
• Enums: EventStatus, VenueType, RecipeCategory, DifficultyLevel, etc.
• Input Types: For mutations and complex arguments

Field Resolution

• Lazy loading of nested data
• Efficient database queries
• Caching support
• Error handling

Validation

• Input validation
• Business rule enforcement
• Type safety
• Required field checking

Development Tools

GraphiQL Interface

Access the GraphiQL interface at /api/graphiql in development mode for:

• Interactive query building
• Schema exploration
• Documentation browsing
• Query testing

Schema Introspection

{
  __schema {
    types {
      name
      description
    }
  }
}

Integration with CQRS/Event Sourcing

The GraphQL API integrates seamlessly with the Commanded CQRS/Event Sourcing system:

• Mutations dispatch commands to aggregates
• Queries read from projections/read models
• Events update read models asynchronously
• Validation occurs at both GraphQL and domain levels

Error Handling

GraphQL provides structured error responses:

{
  "data": null,
  "errors": [
    {
      "message": "Event name is required",
      "locations": [{"line": 2, "column": 3}],
      "path": ["createEvent"]
    }
  ]
}

Performance Considerations

• Use field selection to minimize data transfer
• Leverage nested queries to reduce round trips
• Implement DataLoader for N+1 query prevention
• Cache frequently accessed data
• Monitor query complexity

Migration from REST

To migrate from REST endpoints:

1. Replace REST calls with GraphQL queries/mutations
2. Update client code to use GraphQL syntax
3. Leverage nested queries to reduce API calls
4. Use GraphQL variables for dynamic queries
5. Implement error handling for GraphQL responses

The GraphQL API provides a more powerful, flexible, and efficient way to interact with the Bartendie system while maintaining full compatibility with the existing domain model and CQRS architecture.