# Yemaya API Changelog

All notable changes to the Yemaya API will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

---

## [Unreleased]

### Added
- Version-specific response formats with configurable output
- RFC 7807 Problem Details error responses for API v2
- API Playground at `/playground` for interactive testing
- Comprehensive code examples in multiple languages

### Changed
- Enhanced Scalar API reference with authentication configuration
- Improved error messages with more context

---

## [2024.12.29] - API v2 Beta

### Added

#### API Versioning
- URL-based versioning (`/v1/...`, `/v2/...`)
- Header-based versioning (`X-API-Version: v2`)
- Query parameter versioning (`?api-version=v2`)
- Version deprecation warnings in response headers
- Version sunset policies with configurable dates

#### Version Migration Support
- Migration guide service with step-by-step upgrade paths
- Breaking change detection between versions
- Version compatibility matrix for feature tracking
- Automatic migration path calculation

#### Response Formats
- Cursor-based pagination for v2 (in addition to offset pagination)
- Configurable date formats (ISO 8601, Unix timestamp, Unix milliseconds)
- Optional null value inclusion in responses
- Snake_case/camelCase output options

#### Documentation
- Interactive API Playground
- Multi-language code examples (JavaScript, Python, Go, Ruby, PHP, cURL)
- Comprehensive error code reference
- Webhook documentation with signature verification examples

### Changed
- Error responses now follow RFC 7807 Problem Details format in v2
- Pagination responses use `pageInfo` for cursor-based pagination
- Rate limit headers follow IETF draft specification

### Deprecated
- v1 offset pagination format (still supported, will be removed in v3)
- Simple error format (replaced by RFC 7807)

---

## [2024.12.15] - Initial Release

### Added

#### Authentication
- JWT-based authentication with access and refresh tokens
- OAuth2 social login (Google, GitHub, Discord)
- API key authentication for server-to-server communication
- Session management with revocation support
- Two-factor authentication (TOTP)

#### User Management
- User registration with email verification
- Profile management (name, bio, avatar)
- Preferences and notification settings
- Account deletion with GDPR compliance

#### Projects
- Create, read, update, delete projects
- Project types: film, game, animation, commercial
- Project visibility: private, team, public
- Project member management with roles (owner, admin, editor, viewer)
- Project archiving and restoration

#### Assets
- Asset upload with multipart support
- Asset versioning with history
- Automatic format detection
- Thumbnail generation
- CDN-backed asset delivery
- Asset tagging and categorization

#### Collaboration
- Real-time collaboration via WebSocket
- Comment threads on any resource
- @mentions with notifications
- Activity feed per project
- Presence indicators

#### AI Generation
- Text generation (scripts, dialogue, descriptions)
- Image generation (concepts, storyboards)
- Model selection (Claude, GPT-4, DALL-E 3)
- Generation history and favorites
- Usage quotas per plan

#### Webhooks
- Event subscriptions for all resource types
- Signature verification (HMAC-SHA256)
- Retry policy with exponential backoff
- Webhook logs and debugging tools
- Test endpoint for development

#### Organizations
- Organization management
- Team invitations
- Role-based access control
- Audit logging
- SSO support (SAML 2.0)

#### Search
- Full-text search across resources
- Filters by type, date, owner
- Faceted search results
- Search suggestions

#### Analytics
- Project analytics (views, collaborators)
- Asset usage statistics
- AI generation metrics
- Export to CSV/JSON

#### Admin
- System monitoring and health checks
- User administration
- Feature flags
- Platform announcements
- Rate limit management

### Security
- CORS configuration
- Rate limiting per endpoint
- Request ID tracking
- Secure headers (CSP, HSTS, etc.)
- Input validation and sanitization

### Performance
- Response compression (gzip, brotli)
- ETag caching
- Connection pooling
- Request timing headers

---

## Versioning Policy

### Semantic Versioning
We use date-based versioning for API releases (YYYY.MM.DD).

### Deprecation Policy
- Deprecated features are marked with `Deprecation` header
- Minimum 6 months notice before removal
- Sunset dates published in advance

### Breaking Changes
Breaking changes will only be introduced in new major versions (v1 → v2).

Non-breaking changes include:
- Adding new optional parameters
- Adding new response fields
- Adding new endpoints
- Fixing bugs

Breaking changes include:
- Removing endpoints
- Removing response fields
- Changing response structure
- Changing authentication requirements

---

## Migration Guides

- [Migrating from v1 to v2](./migration-v1-to-v2.md)

---

## Support

- **Documentation:** https://docs.yemaya.io
- **API Reference:** https://api.yemaya.io/reference
- **Status Page:** https://status.yemaya.io
- **Support Email:** api@yemaya.io