🔍 Code Extractor

Flask API endpoint that creates a new version of an existing document with an optional change summary, verifying document ownership before creation.

Purpose

This endpoint handles POST requests to create document versions in a document management system. It authenticates the user, verifies they own the document, accepts a change summary, and delegates version creation to a document service. It's used for version control and tracking document changes over time.

Source Code

def create_document_version(document_id):
    """Create a new version of a document"""
    user_email = get_current_user()
    
    # Verify document ownership
    document = document_service.get_document(document_id)
    if not document or document.owner != user_email:
        return jsonify({'error': 'Document not found or access denied'}), 404
    
    data = request.get_json()
    change_summary = data.get('change_summary', '')
    
    try:
        version_id = document_service.create_document_version(
            document_id, 
            user_email, 
            change_summary
        )
        
        if version_id:
            return jsonify({
                'success': True,
                'version_id': version_id,
                'message': 'Document version created successfully'
            })
        else:
            return jsonify({'error': 'Failed to create document version'}), 500
            
    except Exception as e:
        logger.error(f"Error creating document version: {e}")
        return jsonify({'error': str(e)}), 500

Parameters

Parameter Details

document_id: String identifier for the document to create a version of. Extracted from the URL path (/api/documents/<document_id>/versions). Must correspond to an existing document owned by the authenticated user.

Return Value

Returns a Flask JSON response tuple. On success (200): {'success': True, 'version_id': <string>, 'message': 'Document version created successfully'}. On document not found or access denied (404): {'error': 'Document not found or access denied'}. On service failure (500): {'error': 'Failed to create document version'}. On exception (500): {'error': <error_message>}.

Dependencies

• flask
• logging

Required Imports

from flask import Flask, request, jsonify
import logging

Usage Example

# Client-side usage example
import requests

# Assuming authentication is handled via session/headers
url = 'http://localhost:5000/api/documents/doc123/versions'
headers = {'Authorization': 'Bearer <token>'}
payload = {
    'change_summary': 'Updated introduction section with new data'
}

response = requests.post(url, json=payload, headers=headers)

if response.status_code == 200:
    result = response.json()
    print(f"Version created: {result['version_id']}")
else:
    print(f"Error: {response.json()['error']}")

Best Practices

• Always include authentication token in request headers when calling this endpoint
• Provide meaningful change_summary values to maintain clear version history
• Handle all possible HTTP status codes (200, 404, 500) in client code
• The endpoint enforces ownership verification - users can only version their own documents
• The change_summary parameter is optional but recommended for audit trails
• Ensure document_service is properly initialized before the Flask app starts
• Consider implementing rate limiting for version creation to prevent abuse
• The function logs errors but returns generic error messages to clients for security

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function create_document_v5 83.1% similar

  Flask API endpoint that creates a new document or duplicates an existing document with options to copy or reference sections.

  From: /tf/active/vicechatdev/vice_ai/new_app.py

• function get_document_v3 79.1% similar

  Flask API endpoint that retrieves all versions of a specific document, verifying user ownership before returning the version history.

  From: /tf/active/vicechatdev/vice_ai/new_app.py

• function api_create_document 75.7% similar

  Flask API endpoint that creates a new document with a title and author, returning the created document's details as JSON.

  From: /tf/active/vicechatdev/vice_ai/complex_app.py

• function revert_document_to_version 75.1% similar

  Flask API endpoint that reverts a document to a specific previous version after verifying user ownership and authentication.

  From: /tf/active/vicechatdev/vice_ai/new_app.py

• function update_document_v2 74.7% similar

  Flask API endpoint that updates a document's title and/or description after verifying user ownership and authentication.

  From: /tf/active/vicechatdev/vice_ai/new_app.py