Skip to content

API_DOCUMENTATION_INDEX.md

Latest commit

 

History

History
715 lines (561 loc) · 28 KB

API_DOCUMENTATION_INDEX.md

File metadata and controls

715 lines (561 loc) · 28 KB

Python Alfresco API v1.1 - Complete Documentation Index

This document provides a comprehensive index of all documentation and examples for the Python Alfresco API v1.1, including the modern ClientFactory pattern, hierarchical clients, and three-tier architecture.

📚 Table of Contents

🏗️ Architecture Overview

Factory Pattern

from python_alfresco_api import ClientFactory

# Shared authentication and centralized configuration
factory = ClientFactory(base_url="http://localhost:8080", username="admin", password="admin")

# Create individual clients as needed (all share same authentication session)
auth_client = factory.create_auth_client()
core_client = factory.create_core_client()
search_client = factory.create_search_client()
workflow_client = factory.create_workflow_client()
discovery_client = factory.create_discovery_client()
model_client = factory.create_model_client()
search_sql_client = factory.create_search_sql_client()

# Create master client with all clients initialized
master_client = factory.create_master_client()

Modern Individual Client Architecture

The library uses a clean individual client architecture following enterprise patterns:

Client Purpose Status
AuthClient Authentication, ticket management ✅ 100% Working
CoreClient Content management, nodes, sites ✅ 100% Working
DiscoveryClient Repository information, capabilities ✅ 100% Working
SearchClient Content search (AFTS/CMIS) ✅ 100% Working
WorkflowClient Process and task management ✅ 100% Working
ModelClient Content models, types, aspects ✅ 100% Working
SearchSQLClient SQL-based search ✅ 100% Working

Standalone Pydantic v2 Models

Pydantic v2 models are available separately (not integrated with clients) for AI/LLM integration:

from python_alfresco_api.models.alfresco_core_models import NodeBodyCreate
from python_alfresco_api.models.alfresco_search_models import SearchRequest

# Standalone model usage (NOT for direct client integration)
node_data = NodeBodyCreate(
    name="my-document.txt",
    nodeType="cm:content",
    properties={"cm:title": "My Document"}
)

search_req = SearchRequest(
    query={"query": "test", "language": "afts"},
    paging={"maxItems": 10}
)

# Use with clients via dictionaries
core_client.create_node({"name": "my-document.txt", "nodeType": "cm:content"})

🎯 Essential Operations Guide

📖 ESSENTIAL_OPERATIONS_GUIDE.md - COMPLETE OPERATION COVERAGE

The comprehensive guide covering all essential Alfresco operations with both High-Level Utilities and V1.1 Hierarchical APIs:

🚀 What's Covered:

  • 📁 Content Management - Create folders, upload/download documents, get/update properties, delete nodes
  • 🗂️ Node Operations - Browse repository, manage node paths, simple CRUD operations
  • 🔍 Search Operations - Simple text search, advanced search, CMIS queries, metadata search
  • 📝 Document Versioning - Checkout → Edit → Checkin workflow, auto-versioning, version history, lock management
  • ⚡ Async Operations - Web application patterns with concurrent execution
  • 🏭 Production Patterns - Error handling, batch operations, type safety with Pydantic models

📋 Quick Reference Included:

Operation Category High-Level Utilities V1.1 Hierarchical APIs Best For
Content Management content_utils_highlevel.* core_client.nodes.* Rapid development
Node Operations node_utils_highlevel.* core_client.nodes.* Fine control
Search Operations search_utils.simple_search() search_client.search() Already optimized
Versioning version_utils_highlevel.* core_client.versions.* Document workflows

🎯 Cross-References:

💡 Perfect for: Developers who want comprehensive operation coverage with working code examples for both rapid development (high-level utilities) and fine control (V1.1 hierarchical APIs).

📝 Request Types & Parameter Guide

📖 REQUEST_TYPES_GUIDE.md - COMPREHENSIVE PARAMETER CUSTOMIZATION

Learn how to use typed requests, advanced parameters, and raw client access for maximum flexibility:

🔄 Conversion Utilities & Architecture

📖 CONVERSION_UTILITIES_DESIGN.md - PYDANTIC ↔ ATTRS CONVERSION SOLUTION

Solves the architectural gap between Pydantic models (V1.1 hierarchical) and attrs models (raw clients):

  • 🎯 Problem Analysis - Current manual conversion inconsistencies and Search API gaps
  • 🏗️ Three-Layer Solution - Enhanced FieldMappingMixin, conversion utilities, high-level wrappers
  • ⚡ Proof-of-Concept - Working conversion utilities with automatic field mapping
  • 🚀 Implementation Plan - Phased approach for seamless integration without breaking changes

Key Benefits:

# Instead of manual conversion:
body = NodeBodyCreate(name=request.name, node_type=getattr(request.node_type, 'value'...))

# Use automatic conversion:
attrs_dict = pydantic_to_attrs_dict(request)
body = NodeBodyCreate.from_dict(attrs_dict)

# Or high-level Search wrapper:
search = AlfrescoSearchRequest(query="annual report", content_types=["cm:content"])
raw_request = search.to_raw_search_request()  # Automatic conversion
  • 🔍 "Detailed" Methods Explained - HTTP Response details vs content (Response[T] vs Optional[T])
  • 📋 Node Request Types - CreateNodeRequest, UpdateNodeRequest, CopyNodeRequest, MoveNodeRequest
  • 🔍 Search Request Types - SearchRequest, RequestQuery, faceting, highlighting, AFTS/CMIS/Lucene
  • 🛠️ Advanced Parameters - Properties, aspects, include options, field selection, query languages
  • ⚙️ Raw Client Access - When high-level methods aren't enough
  • 🚫 Current Limitations - What's not supported and workarounds

Key Insights:

# Four Method Patterns (confirmed working):
client.nodes.create(request)                    # → NodeResponse (content only)
client.nodes.create_async(request)              # → NodeResponse (content only)
client.nodes.create_detailed(request)           # → Response[NodeEntry] (full HTTP)
client.nodes.create_detailed_async(request)     # → Response[NodeEntry] (full HTTP)

# Advanced parameter usage:
result = client.nodes.list_children(
    node_id="-my-",
    include=["properties", "allowableOperations"],
    fields=["id", "name", "properties"],
    where="isFile=true",
    order_by="name ASC"
)

# Search with raw client models:
from python_alfresco_api.raw_clients.alfresco_search_client.search_client.models import SearchRequest, RequestQuery
search_request = SearchRequest(query=RequestQuery(query="TYPE:cm:content"))
result = client.search.search(body=search_request)

🛠️ Development & Code Generation

📖 PACKAGE_DEVELOPERS_GUIDE.md - COMPREHENSIVE PACKAGE DEVELOPMENT GUIDE

Complete documentation for developing, contributing to, and maintaining the python-alfresco-api package:

  • 🔄 3-Step Generation Process - Pydantic models → HTTP clients → High-level APIs
  • 🛠️ Development Workflows - Standard development, testing, formatting, contribution guidelines
  • ⚙️ Generation Configuration - Complete config system with short client names
  • 🏗️ Architecture Overview - Generated structure and V1.1 hierarchical benefits
  • 🛡️ Safety & Protection - Protected directories and backup recommendations

Generation Pipeline:

# STEP 1: Pydantic Models (datamodel-code-generator)
# Input: OpenAPI 3.0 specs → Output: python_alfresco_api/models/*.py

# STEP 2: HTTP Clients (openapi-python-client) 
# Input: OpenAPI 3.0 + config → Output: python_alfresco_api/raw_clients/

# STEP 3: High-Level APIs (generate_all_apis_v11.py)
# Input: Raw client source → Output: python_alfresco_api/clients/ hierarchy

Key Features:

  • ✅ Complete automation - Full package regeneration from OpenAPI specs
  • ✅ Protection mechanisms - Custom code preserved during regeneration
  • ✅ Short client names - 64-81% shorter than defaults (auth_client vs alfresco_content_services_rest_api_client)
  • ✅ Configuration-driven - YAML configs for all 7 APIs in config/ folder
  • ✅ Three-tier architecture - Global → API → Operation models with perfect locality

🔧 Individual API Clients

1. Authentication API ✅ 100% WORKING

Purpose: User authentication, ticket management, session handling

from python_alfresco_api import ClientFactory

# Use factory pattern for shared authentication
factory = ClientFactory(base_url="http://localhost:8080", username="admin", password="admin")
auth_client = factory.create_auth_client()

# Create authentication ticket
ticket = auth_client.create_ticket({
    "userId": "admin",
    "password": "admin"
})

# Validate ticket
is_valid = auth_client.validate_ticket(ticket.entry.id)

Key Features:

  • ✅ Ticket-based authentication
  • ✅ Session management
  • ✅ Login/logout functionality
  • ✅ Ticket validation

2. Core API ✅ 100% WORKING

Purpose: Complete content management - nodes, sites, people, groups, and more

from python_alfresco_api import ClientFactory

# Use factory pattern for shared authentication
factory = ClientFactory(base_url="http://localhost:8080", username="admin", password="admin")
core_client = factory.create_core_client()

# Get nodes (files and folders)
nodes = core_client.get_nodes()

# Get sites
sites = core_client.get_sites()

# Get people
people = core_client.get_people()

Available Operations:

  • ✅ Nodes API - File/folder operations, content management
  • ✅ Sites API - Site management and collaboration
  • ✅ People API - User management and profiles
  • ✅ Groups API - Group management and membership
  • ✅ Actions API - Content actions and operations
  • ✅ Comments API - Content comments and discussions
  • ✅ Ratings API - Content ratings and reviews
  • ✅ Tags API - Content tagging and organization
  • ✅ Favorites API - User favorites management
  • ✅ Versions API - Document version control
  • ✅ Renditions API - Content transformations
  • ✅ Shared Links API - Public link sharing
  • ✅ Downloads API - Bulk download operations
  • ✅ Audit API - System audit trails
  • ✅ Activities API - Activity feeds
  • ✅ Preferences API - User preferences
  • ✅ Queries API - Advanced querying
  • ✅ Trashcan API - Deleted content management
  • ✅ Probes API - System health checks
  • ✅ Networks API - Multi-tenant networks

3. Discovery API ✅ 100% WORKING

Purpose: Repository information, server capabilities, system status

from python_alfresco_api import ClientFactory

# Use factory pattern for shared authentication
factory = ClientFactory(base_url="http://localhost:8080", username="admin", password="admin")
discovery_client = factory.create_discovery_client()

# Get repository information
repo_info = discovery_client.get_repository_info()
print(f"Alfresco version: {repo_info.entry.repository.version.major}.{repo_info.entry.repository.version.minor}")

Key Features:

  • ✅ Repository information and version
  • ✅ Server capabilities discovery
  • ✅ System status checking

4. Search API ✅ 100% WORKING

Purpose: Content search using AFTS (Alfresco Full Text Search) and CMIS queries

from python_alfresco_api import ClientFactory

# Use factory pattern for shared authentication
factory = ClientFactory(base_url="http://localhost:8080", username="admin", password="admin")
search_client = factory.create_search_client()

# AFTS search (Alfresco Full Text Search)
afts_request = {
    "query": {
        "query": "test document",
        "language": "afts"
    },
    "paging": {
        "maxItems": 10,
        "skipCount": 0
    }
}

# CMIS search (SQL-like queries)
cmis_request = {
    "query": {
        "query": "SELECT * FROM cmis:document WHERE cmis:name LIKE 'test%'",
        "language": "cmis"
    }
}

results = search_client.search(afts_request)  # or cmis_request

Key Features:

  • ✅ AFTS (Alfresco Full Text Search) - full-text queries with operators (AND, OR, NOT)
  • ✅ CMIS query support - SQL-like structured queries
  • ✅ Advanced filtering and pagination
  • ✅ Flexible search requests with dictionary input

5. Workflow API ✅ 100% WORKING

Purpose: Process definitions, tasks, workflow management

from python_alfresco_api import ClientFactory

# Use factory pattern for shared authentication
factory = ClientFactory(base_url="http://localhost:8080", username="admin", password="admin")
workflow_client = factory.create_workflow_client()

# Get process definitions
processes = workflow_client.get_process_definitions()

# Get tasks
tasks = workflow_client.get_tasks()

Key Features:

  • ✅ Process definition management
  • ✅ Task management
  • ✅ Workflow instance control

6. Model API ✅ 100% WORKING

Purpose: Content models, types, aspects management

from python_alfresco_api import ClientFactory

# Use factory pattern for shared authentication
factory = ClientFactory(base_url="http://localhost:8080", username="admin", password="admin")
model_client = factory.create_model_client()

# Get content models
models = model_client.get_models()

# Get types
types = model_client.get_types()

# Get aspects
aspects = model_client.get_aspects()

Key Features:

  • ✅ Content model management
  • ✅ Type definitions
  • ✅ Aspect management

7. Search SQL API ✅ 100% WORKING

Purpose: SQL-based content search (requires Solr configuration)

from python_alfresco_api import ClientFactory

# Use factory pattern for shared authentication
factory = ClientFactory(base_url="http://localhost:8080", username="admin", password="admin")
search_sql_client = factory.create_search_sql_client()

# SQL-based search requires specific SOLR configuration

Key Features:

  • ✅ SQL-based search queries
  • ✅ Advanced filtering capabilities
  • ✅ Solr integration

👑 Master Client

Unified Access Pattern with Dot Syntax

from python_alfresco_api import ClientFactory

# Create factory with shared authentication
factory = ClientFactory(
    base_url="http://localhost:8080",
    username="admin",
    password="admin"
)

# Create master client with dot syntax access
master_client = factory.create_master_client()

# Access individual APIs through elegant dot syntax
repo_info = master_client.discovery.get_repository_info()
nodes = master_client.core.get_nodes()
search_results = master_client.search.search(search_request)
processes = master_client.workflow.get_process_definitions()
models = master_client.model.get_models()
sql_results = master_client.search_sql.search(sql_request)
auth_ticket = master_client.auth.create_ticket({"userId": "admin", "password": "admin"})

# All clients share the same authentication session
print(f"Repository: {master_client.discovery.get_repository_info().entry.repository.name}")

Benefits:

  • ✅ Single authentication across all APIs
  • ✅ Elegant dot syntax access (e.g., master_client.core.get_nodes())
  • ✅ All 7 API clients with shared session
  • ✅ Simplified client management
  • ✅ Consistent error handling
  • ✅ Automatic session management
  • ✅ Type-safe client access with proper IDE support

Available API Clients:

  • master_client.auth - Authentication API
  • master_client.core - Core Repository API
  • master_client.discovery - Discovery API
  • master_client.search - Search API
  • master_client.workflow - Workflow API
  • master_client.model - Model API
  • master_client.search_sql - Search SQL API

📖 Examples

Working Examples Directory

All examples are located in the examples/ directory and are fully functional:

Example File Description Status
basic_usage.py ClientFactory and individual clients ✅ Working
live_test.py Live server integration test ✅ Working
llm_integration.py AI/LLM integration examples ✅ Working
auth_examples.py Authentication patterns ✅ Working
auth_helpers.py Authentication utilities ✅ Working
master_client_examples.py Master client usage patterns ✅ Working

Example Categories

✅ Core Functionality Examples

# ClientFactory Pattern
from python_alfresco_api import ClientFactory

factory = ClientFactory(
    base_url="http://localhost:8080",
    username="admin",
    password="admin"
)

# Get all clients
clients = factory.create_all_clients()

# Use individual clients
repo_info = clients['discovery'].get_repository_info()

✅ Authentication Examples

# Individual auth client using factory pattern
from python_alfresco_api import ClientFactory

factory = ClientFactory(base_url="http://localhost:8080", username="admin", password="admin")
auth_client = factory.create_auth_client()
ticket = auth_client.create_ticket({"userId": "admin", "password": "admin"})

✅ Search Examples

# AFTS search (full-text with operators)
afts_request = {
    "query": {"query": "test document", "language": "afts"},
    "paging": {"maxItems": 10}
}

# CMIS search (SQL-like structured queries)
cmis_request = {
    "query": {
        "query": "SELECT * FROM cmis:document WHERE cmis:name LIKE 'test%'",
        "language": "cmis"
    }
}

results = search_client.search(afts_request)  # or cmis_request

# Pydantic models available separately for validation
from python_alfresco_api.models.alfresco_search_models import SearchRequest
validated_request = SearchRequest(**afts_request)  # Standalone validation

✅ LLM/AI Integration Examples

# Perfect for AI applications
from python_alfresco_api.models.alfresco_core_models import NodeBodyCreate

# Type-safe model for AI tools
node_data = NodeBodyCreate(
    name="ai-generated-document.txt",
    nodeType="cm:content",
    properties={"cm:title": "AI Generated Content"}
)

# Serialize for AI systems
json_data = node_data.model_dump_json()

🔐 Authentication & Security

Authentication Guide

Modern Authentication Patterns

ClientFactory with Authentication (Recommended)

from python_alfresco_api import ClientFactory

# Automatic authentication across all clients
factory = ClientFactory(
    base_url="http://localhost:8080",
    username="admin",
    password="admin"
)

# Option 1: All clients at once
clients = factory.create_all_clients()

# Option 2: Individual clients as needed
auth_client = factory.create_auth_client()
core_client = factory.create_core_client()
discovery_client = factory.create_discovery_client()
search_client = factory.create_search_client()
workflow_client = factory.create_workflow_client()
model_client = factory.create_model_client()
search_sql_client = factory.create_search_sql_client()

# Option 3: Master client with dot syntax
master_client = factory.create_master_client()
# Access APIs: master_client.core, master_client.search, etc.

Manual Authentication with AuthUtil

from python_alfresco_api import ClientFactory, AuthUtil

# Manual authentication control
auth = AuthUtil(
    base_url="http://localhost:8080",
    username="admin",
    password="admin"
)

# Use AuthUtil with factory
factory = ClientFactory(auth_util=auth)
core_client = factory.create_core_client()  # Uses provided AuthUtil

Security Features

  • ✅ Ticket-based Authentication - Secure session management
  • ✅ Automatic Token Refresh - Seamless session handling
  • ✅ SSL/TLS Support - Secure communication
  • ✅ Error Handling - Comprehensive auth error management

🧪 Testing Documentation

Test Coverage

  • Test Success Rate: 67 tests available (11 core + 45 high-level API + 6 coverage recovery + 5 integration)
  • Code Coverage: 44-46% with comprehensive high-level API tests (target: 80%+)
  • Test Files: All organized in tests/ directory
  • Live Integration: Tested with Alfresco Community 23.2.0 and 25.1

Running Tests

# Run basic tests (~28% coverage) 
python run_tests.py

# Run high-level API tests for 44-46% coverage (recommended baseline)
pytest tests/test_all_gets_high_level.py tests/test_all_gets_high_level_async.py --cov=python_alfresco_api --cov-report=html

# Run all 67 available tests
pytest tests/ --cov=python_alfresco_api

# Run specific test categories
pytest tests/test_basic.py tests/test_simple.py  # Core foundation (11 tests)
pytest tests/test_comprehensive_coverage_recovery.py  # Coverage recovery (6 tests)
pytest tests/test_mcp_v11_true_high_level_apis_fixed.py  # MCP integration

# Run specific GET test files
pytest tests/test_all_gets_high_level.py -v  # 19 sync GET tests
pytest tests/test_all_gets_high_level_async.py -v  # 19 async GET tests  
pytest tests/test_all_gets_high_level_detailed.py -v  # 3 detailed sync GET tests
pytest tests/test_all_gets_high_level_detailed_async.py -v  # 4 detailed async GET tests

Test Categories

Test Category Count Coverage Description
Core Foundation 11 tests ~28% Basic functionality (test_basic.py + test_simple.py)
High-Level GET API Coverage 45 tests ~44-46% Comprehensive GET operations across all 18 Core API subsections (sync + async + detailed)
Coverage Recovery 6 tests Additional Factory patterns, model instantiation, auth operations
Integration Tests 5+ tests Varies MCP server integration, live server testing
Total Available 67 tests 44-46% Complete test suite with pytest collection

High-Level GET Tests Breakdown (45 tests)

Test File Count Description
test_all_gets_high_level.py 19 tests Sync GET operations across all 18 Core API subsections
test_all_gets_high_level_async.py 19 tests Async GET operations across all 18 Core API subsections
test_all_gets_high_level_detailed.py 3 tests Detailed sync GET operations with parameter variations
test_all_gets_high_level_detailed_async.py 4 tests Detailed async GET operations with parameter variations

Core API Subsections Covered by GET Tests:

  • nodes (file/folder operations) - sites (site management) - people (user profiles)
  • groups (group management) - tags (content tagging) - favorites (user favorites)
  • trashcan (deleted content) - activities (activity feeds) - audit (audit trails)
  • actions (content actions) - preferences (user preferences) - probes (health checks)
  • queries (advanced queries) - ratings (content ratings) - renditions (transformations)
  • shared_links (public links) - networks (multi-tenant) - downloads (bulk downloads)

What GET Tests Validate:

  • ✅ Client Creation - All 18 Core API subsection clients can be created successfully
  • ✅ Method Availability - GET/list/find methods exist and are callable across all subsections
  • ✅ Parameter Handling - Advanced parameters (fields, include, max_items, skip_count, order_by, where, relations)
  • ✅ Sync/Async Patterns - Both synchronous and asynchronous operation patterns work
  • ✅ Error Handling - Graceful handling when operations fail (expected in test environments)
  • ✅ Code Path Coverage - Comprehensive coverage of the V1.1 hierarchical architecture

🎯 Documentation Navigation Guide

By User Type

🆕 New Users

  1. README.md - Project overview and installation
  2. Quick Start - Get started immediately
  3. examples/basic_usage.py - Working code examples
  4. Authentication Guide - Authentication setup

🔧 Developers

  1. Architecture Overview - Understand the design
  2. Individual API Clients - Detailed API docs
  3. examples/ - Complete working examples
  4. Testing Documentation - Test approach

🤖 AI/LLM Developers

  1. examples/llm_integration.py - AI integration patterns
  2. Standalone Pydantic Models - Pydantic v2 models (separate from clients)
  3. README.md MCP Section - MCP server examples

By Use Case

Content Management

Search & Discovery

User & Workflow Management

System Integration

📊 Current Status Summary

✅ Production Ready (100% Working)

  • All 7 API Clients - Complete functionality
  • ClientFactory Pattern - Modern enterprise architecture
  • Master Client - Unified access pattern
  • Standalone Pydantic Models - 328+ Pydantic v2 models (available separately)
  • Authentication - Comprehensive auth support
  • Testing - 48% code coverage with 67 comprehensive tests (baseline achieved)
  • Documentation - Complete guides and examples
  • Live Integration - Validated with Alfresco Community 23.2.0 and 25.1

📈 Success Metrics

  • 7/7 APIs fully functional (100%)
  • 67 comprehensive tests available (core + high-level API + coverage recovery + integration)
  • 44-46% code coverage baseline achieved (target: 80%+ for production)
  • 100% documentation coverage
  • 100% working examples
  • Live server validation ✅

🎉 Getting Started Recommendation

For new users, we recommend this path:

  1. README.md - Get the big picture and install
  2. Quick Start - Try the ClientFactory pattern
  3. examples/basic_usage.py - See working code
  4. examples/live_test.py - Test with your server
  5. Choose your pattern: Individual Clients (enterprise) or Master Client (simplified) - both use ClientFactory
  6. Explore specific APIs based on your needs

The ClientFactory pattern is the foundation - choose Individual Clients or Master Client access style! 🚀