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:

{
-  "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