thrillwiki_django_no_react/docs/version_control_api.md

Version Control System API Documentation

Overview

The version control system provides a comprehensive API for managing content versioning, branching, and merging across different models in the system.

Core Models

VersionBranch

Represents a branch in the version control system.

class VersionBranch:
    name: str           # Branch name (unique)
    metadata: JSONField # Branch metadata
    is_active: bool    # Branch status
    created_at: datetime
    updated_at: datetime

ChangeSet

Represents a set of changes to a versioned object.

class ChangeSet:
    branch: ForeignKey      # Reference to VersionBranch
    content_type: ForeignKey # ContentType of the changed object
    object_id: int         # ID of the changed object
    data: JSONField        # Change data
    status: str           # Status (pending, applied, conflict)
    created_at: datetime
    applied_at: datetime

API Endpoints

Branch Management

Create Branch

POST /api/v1/version-control/branches/

Request body:

{
    "name": "feature/new-branch",
    "metadata": {
        "type": "feature",
        "description": "New feature branch"
    }
}

Response:

{
    "id": 1,
    "name": "feature/new-branch",
    "metadata": {
        "type": "feature",
        "description": "New feature branch"
    },
    "is_active": true,
    "created_at": "2025-02-07T09:00:00Z"
}

Switch Branch

POST /api/v1/version-control/branches/{branch_id}/switch/

Response:

{
    "status": "success",
    "branch": {
        "id": 1,
        "name": "feature/new-branch"
    }
}

Change Management

Create Change

POST /api/v1/version-control/changes/

Request body:

{
    "branch_id": 1,
    "content_type": "parks.park",
    "object_id": 123,
    "data": {
        "name": "Updated Name",
        "description": "Updated description"
    }
}

Response:

{
    "id": 1,
    "branch": 1,
    "status": "pending",
    "created_at": "2025-02-07T09:05:00Z"
}

Apply Change

POST /api/v1/version-control/changes/{change_id}/apply/

Response:

{
    "status": "success",
    "change": {
        "id": 1,
        "status": "applied",
        "applied_at": "2025-02-07T09:06:00Z"
    }
}

Merge Operations

Merge Branch

POST /api/v1/version-control/branches/{source_id}/merge/

Request body:

{
    "target_branch_id": 2
}

Response:

{
    "status": "success",
    "conflicts": []
}

Resolve Conflicts

POST /api/v1/version-control/merge/resolve/

Request body:

{
    "merge_id": 1,
    "resolutions": [
        {
            "field": "name",
            "value": "Resolved Name"
        }
    ]
}

Response:

{
    "status": "success",
    "merge": {
        "id": 1,
        "status": "completed"
    }
}

Model Integration

Adding Version Control to Models

To make a model version-controlled, inherit from HistoricalModel:

from history_tracking.models import HistoricalModel

class YourModel(HistoricalModel):
    name = models.CharField(max_length=255)
    
    def save(self, *args, **kwargs):
        # Get the branch from context
        current_branch = get_current_branch()
        
        if current_branch:
            # Save in branch context
            super().save(*args, **kwargs)
        else:
            # Save in main branch
            with ChangesetContextManager(branch=main_branch):
                super().save(*args, **kwargs)

Version Control Methods

Each versioned model has access to these methods:

get_version_info()

Returns version control information for the object:

info = model.get_version_info()
# Returns:
{
    'latest_changes': [ChangeSet],
    'active_branches': [VersionBranch],
    'current_branch': VersionBranch,
    'total_changes': int
}

get_changes()

Returns all changes for the object:

changes = model.get_changes()
# Returns QuerySet of ChangeSet objects

JavaScript Integration

Version Control UI

Initialize version control UI:

import { initVersionControl } from 'version-control.js';

initVersionControl({
    container: '#version-control-panel',
    onChange: (branch) => {
        // Handle branch change
    }
});

Branch Operations

Switch branches:

import { switchBranch } from 'version-control.js';

switchBranch(branchId).then(response => {
    if (response.status === 'success') {
        // Handle successful branch switch
    }
});

Merge Operations

Handle merge conflicts:

import { handleMergeConflicts } from 'version-control.js';

handleMergeConflicts(conflicts).then(resolutions => {
    // Handle conflict resolutions
});

Error Handling

The API uses standard HTTP status codes:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 409: Conflict (merge conflicts)
• 500: Internal Server Error

Error responses include detailed information:

{
    "status": "error",
    "message": "Detailed error message",
    "code": "ERROR_CODE",
    "details": {
        // Additional error details
    }
}

Rate Limiting

API endpoints are rate-limited:

• Authenticated users: 100 requests per minute
• Anonymous users: 20 requests per minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1623456789

Monitoring

Monitor version control operations through the monitoring dashboard:

GET /version-control/monitoring/

The dashboard provides real-time metrics for:

• Branch operations
• Merge success rates
• Change tracking overhead
• Error rates
• System health