API Documentation

Welcome to the comprehensive documentation for the Ivyi Platform API. This guide covers everything you need to integrate with our backend services.

🎁 About Ivyi API

The Ivyi API provides the backend infrastructure for managing users, occasions, gifts, and social interactions. It follows RESTful conventions and is built with modern, scalable technologies designed for performance and reliability.

🏗️ Technology Stack

• Runtime: Node.js 22+
• Framework: Express.js with TypeScript
• Database: PostgreSQL with Drizzle ORM
• Background Jobs: PGBoss
• Architecture: Domain-Driven Design (DDD)
• Authentication: JWT-based
• Documentation: OpenAPI/Swagger 3.0

🎯 Core API Domains

👥 Users API

Complete user management system with:

• Authentication & Authorization: Secure JWT-based login/logout
• Profile Management: Update user information and preferences
• Social Connections: Friend relationships and network building
• Account Security: Password management and privacy controls

🎉 Occasions API

Full event lifecycle management:

• Occasion Creation: Create birthdays, weddings, graduations, and more
• Occasion Management: Update details, manage timelines, coordinate activities

🎁 Gifts API

Comprehensive gifting coordination:

• Group Gifting: Coordinate multiple contributors for single gifts
• Gift Tracking: Monitor delivery and receipt status

🚀 Getting Started

Prerequisites

• Node.js 20+
• PostgreSQL database
• npm or yarn package manager

Quick Setup

1. Navigate to API directory

   cd apps/api

2. Install dependencies

   npm install

3. Configure environment

   cp .env.example .env
   # Edit .env with your database and JWT settings

4. Setup database

   npm run db:setup
   npm run db:migrate
   npm run db:seed

5. Start development

   npm run dev

📚 API Documentation

Core Documentation

• 📖 API Overview - This page - Complete API guide and getting started
• 🎮 Controllers - Request handling patterns and response formatting
• ⚙️ Operations - Business logic and data operations
• 🏗️ Architecture - System design and component interactions

Architecture Documentation

• 🔧 Workers & Jobs - Background job processing and event handling
• 📦 Queues - Message queuing and job distribution

The Ivyi API is fully documented using OpenAPI 3.0 and accessible through an interactive Swagger UI. This is the recommended way to explore and test all available endpoints.

Accessing Documentation

When running the API locally, access the interactive documentation at:

• Swagger UI: http://localhost:3000/api-docs
• OpenAPI JSON: http://localhost:3000/api-docs/json

What You Can Do

The interactive Swagger UI provides:

• 🔍 Explore Endpoints: Browse all available API endpoints organized by domain
• 🧪 Test in Browser: Make authenticated requests directly in the interface
• 📝 View Schemas: See detailed request/response models
• 🔐 Authentication Testing: Built-in JWT authentication testing
• 💻 Code Examples: Multiple programming language examples
• 📖 Real-time Validation: See validation rules and error responses

API Domains Available

• 🔐 Authentication: User registration, login, logout
• 👥 Users: Profile management and social features
• 🎉 Occasions: Event creation, invitations, RSVP tracking
• 🎁 Gifts: Gift catalog, wish lists, group gifting

Why Use Interactive Docs?

• Always Up-to-Date: Reflects latest API changes automatically
• No Manual Sync: Eliminates documentation version conflicts
• Interactive Testing: Test endpoints before writing code
• Schema Clarity: Visual representation of data structures
• Authentication Helper: Easy JWT token management for testing

🔒 Authentication & Security

JWT Token Management

• Token Generation: Secure token creation on login
• Token Validation: Middleware for protected routes
• Token Refresh: Automatic token renewal
• Token Storage: HTTP-only cookie security

Request Validation

• Schema Validation: Zod-based request validation
• Input Sanitization: Prevent XSS and injection
• Error Responses: Consistent error format
• Rate Limiting: Configurable request limits

📊 Response Format

JSON:API Standard

All API responses follow JSON:API specification:

{
  "data": {
    "type": "user",
    "id": "uuid",
    "attributes": { ... }
  },
  "meta": {
    "total": 1,
    "page": 1
  }
}

Error Handling

Standardized error responses:

{
  "errors": [
    {
      "title": "Validation Error",
      "detail": "Email is required",
      "status": "400"
    }
  ]
}

🛠️ Development Tools

Available Scripts

• npm run dev - Start development server with hot reload
• npm run build - Build for production
• npm run test - Run test suite
• npm run lint - Code quality checks
• npm run type-check - TypeScript validation

Code Quality Assurance

• ESLint: Consistent code style
• Prettier: Automatic formatting
• TypeScript: Compile-time type checking
• Husky: Git hooks for quality gates

🌐 Interactive Documentation

When running the API locally, access:

• Swagger UI: http://localhost:3000/api-docs
• OpenAPI JSON: http://localhost:3000/api-docs/json

Interactive documentation includes:

• Try it out: Test endpoints directly in browser
• Authentication: Built-in JWT testing
• Schema Explorer: Detailed request/response models
• Code Examples: Multiple language examples