CODEX_ADK/BACKEND/docs/CHANGELOG.md

# API Changelog

This document tracks **breaking changes only** to the Codex API. Non-breaking additions and bug fixes are not included here.

## Format
Each entry should include:
- **Date**: When the change was introduced
- **Version**: API version (when versioning is implemented)
- **Endpoint**: Affected endpoint(s)
- **Change**: Description of what changed
- **Migration**: How to update client code
- **Reason**: Why the change was necessary

---

## [1.0.0-mvp] - 2025-10-26

### MVP Release - Frontend Ready

This is the initial MVP release with all core functionality complete and tested. The backend is **production-ready** for frontend integration.

#### Commands (6 endpoints)
- **POST /api/command/createAgent** - Create new AI agent with model configuration
- **POST /api/command/updateAgent** - Update existing agent settings
- **POST /api/command/deleteAgent** - Soft delete an agent
- **POST /api/command/createConversation** - Create conversation (returns Guid)
- **POST /api/command/startAgentExecution** - Start agent execution (returns Guid)
- **POST /api/command/completeAgentExecution** - Complete execution with results

#### Queries (4 endpoints)
- **POST /api/query/health** - Health check endpoint
- **POST /api/query/getAgent** - Get single agent by ID
- **POST /api/query/getAgentExecution** - Get execution details by ID
- **POST /api/query/getConversation** - Get conversation with messages and executions

#### List Endpoints (6 GET endpoints)
- **GET /api/agents** - List all agents (limit: 100 most recent)
- **GET /api/conversations** - List all conversations (limit: 100 most recent)
- **GET /api/executions** - List all executions (limit: 100 most recent)
- **GET /api/agents/{id}/conversations** - Get conversations for specific agent
- **GET /api/agents/{id}/executions** - Get execution history for specific agent
- **GET /api/executions/status/{status}** - Filter executions by status

#### Security & Infrastructure
- CORS configured for development (any localhost port) and production (configurable)
- Rate limiting (1000 requests/minute per client)
- Global exception handling middleware
- FluentValidation on all commands
- API key encryption for cloud providers (AES-256)

#### Documentation
- Complete API reference in `docs/COMPLETE-API-REFERENCE.md`
- Architecture documentation
- XML documentation on all commands/queries
- Enum reference for frontend integration

#### Database
- PostgreSQL with EF Core
- Full schema with migrations
- Soft delete support
- Proper indexing for performance

#### Design Decisions
- **Pragmatic over Perfect**: Simple GET endpoints instead of complex dynamic query infrastructure
- **MVP-First**: 100-item limits are sufficient for initial use case
- **No Pagination**: Can be added in v2 based on actual usage patterns
- **Client-Side Filtering**: Frontend can filter/sort small datasets efficiently

#### Known Limitations (Non-Blocking)
- Authentication not yet implemented (documented for v2)
- Swagger documentation only includes 5 endpoints (OpenHarbor limitation)
  - All 16 endpoints are **functional and tested**
  - Complete documentation provided in markdown format
- No real-time updates (WebSockets/SignalR planned for v2)

#### Next Steps
- Frontend team can start integration immediately
- Use `docs/COMPLETE-API-REFERENCE.md` as API contract
- Dynamic filtering/pagination can be added in v2 if needed

---

## [Unreleased]

### Future Enhancements
- JWT authentication and authorization
- Real-time execution updates via SignalR
- Advanced filtering and pagination (if usage patterns require it)
- API versioning strategy
- Distributed caching layer

---

## Example Entry Format

### 2025-01-15 - v2.0

#### POST /api/command/UpdateUser
**Change**: `username` field changed from optional to required

**Migration**:
```diff
{
-  "username": null,
+  "username": "required_value",
   "email": "user@example.com"
}
```

**Reason**: Data integrity requirements - all users must have unique usernames

---

## Guidelines for Maintaining This Log

### What qualifies as a breaking change?
- Removing or renaming endpoints
- Removing or renaming request/response properties
- Changing property types (string → number, nullable → required, etc.)
- Adding required fields to existing requests
- Changing endpoint HTTP methods
- Modifying authentication requirements
- Changing error response formats

### What is NOT a breaking change?
- Adding new optional fields
- Adding new endpoints
- Bug fixes that restore documented behavior
- Performance improvements
- Internal refactoring

### Process
1. Before making a breaking change, discuss with team
2. Update this CHANGELOG.md with the planned change
3. Notify frontend/API consumers with reasonable notice period
4. Implement the change
5. Re-export `openapi.json` via `export-openapi.sh`
6. Verify frontend teams have updated their clients

---

*Last updated: 2025-01-26*