Migrating APIs

API migrations are a common task in large codebases. Whether you’re updating a deprecated function, changing parameter names, or modifying return types, Graph-sitter makes it easy to update all call sites consistently.

Common Migration Scenarios

Renaming Parameters

When updating parameter names across an API, you need to update both the function definition and all call sites:

# Find the API function to update
api_function = codebase.get_function("process_data")

# Update the parameter name
old_param = api_function.get_parameter("input")
old_param.rename("data")

# All call sites are automatically updated:
# process_data(input="test") -> process_data(data="test")

See dependencies and usages for more on updating parameter names and types.

Adding Required Parameters

When adding a new required parameter to an API:

# Find all call sites before modifying the function
call_sites = list(api_function.call_sites)

# Add the new parameter
api_function.add_parameter("timeout: int")

# Update all existing call sites to include the new parameter
for call in call_sites:
    call.add_argument("timeout=30")  # Add with a default value

See function calls and callsites for more on handling call sites.

Changing Parameter Types

When updating parameter types:

# Update the parameter type
param = api_function.get_parameter("user_id")
param.type = "UUID"  # Change from string to UUID

# Find all call sites that need type conversion
for call in api_function.call_sites:
    arg = call.get_arg_by_parameter_name("user_id")
    if arg:
        # Convert string to UUID
        arg.edit(f"UUID({arg.value})")

See working with type annotations for more on changing parameter types.

Deprecating Functions

When deprecating an old API in favor of a new one:

old_api = codebase.get_function("old_process_data")
new_api = codebase.get_function("new_process_data")

# Add deprecation warning
old_api.add_decorator('@deprecated("Use new_process_data instead")')

# Update all call sites to use the new API
for call in old_api.call_sites:
    # Map old arguments to new parameter names
    args = [
        f"data={call.get_arg_by_parameter_name('input').value}",
        f"timeout={call.get_arg_by_parameter_name('wait').value}"
    ]
    
    # Replace the old call with the new API
    call.replace(f"new_process_data({', '.join(args)})")

Bulk Updates to Method Chains

When updating chained method calls, like database queries or builder patterns:

# Find all query chains ending with .execute()
for execute_call in codebase.function_calls:
    if execute_call.name != "execute":
        continue
        
    # Get the full chain
    chain = execute_call.call_chain
    
    # Example: Add .timeout() before .execute()
    if "timeout" not in {call.name for call in chain}:
        execute_call.insert_before("timeout(30)")

Handling Breaking Changes

When making breaking changes to an API, it’s important to:

1. Identify all affected call sites
2. Make changes consistently
3. Update related documentation
4. Consider backward compatibility

Here’s a comprehensive example:

def migrate_api_v1_to_v2(codebase):
    old_api = codebase.get_function("create_user_v1")
    
    # Document all existing call patterns
    call_patterns = {}
    for call in old_api.call_sites:
        args = [arg.source for arg in call.args]
        pattern = ", ".join(args)
        call_patterns[pattern] = call_patterns.get(pattern, 0) + 1
    
    print("Found call patterns:")
    for pattern, count in call_patterns.items():
        print(f"  {pattern}: {count} occurrences")
    
    # Create new API version
    new_api = old_api.copy()
    new_api.rename("create_user_v2")
    
    # Update parameter types
    new_api.get_parameter("email").type = "EmailStr"
    new_api.get_parameter("role").type = "UserRole"
    
    # Add new required parameters
    new_api.add_parameter("tenant_id: UUID")
    
    # Update all call sites
    for call in old_api.call_sites:
        # Get current arguments
        email_arg = call.get_arg_by_parameter_name("email")
        role_arg = call.get_arg_by_parameter_name("role")
        
        # Build new argument list with type conversions
        new_args = [
            f"email=EmailStr({email_arg.value})",
            f"role=UserRole({role_arg.value})",
            "tenant_id=get_current_tenant_id()"
        ]
        
        # Replace old call with new version
        call.replace(f"create_user_v2({', '.join(new_args)})")
    
    # Add deprecation notice to old version
    old_api.add_decorator('@deprecated("Use create_user_v2 instead")')

# Run the migration
migrate_api_v1_to_v2(codebase)

Best Practices

1. Analyze First: Before making changes, analyze all call sites to understand usage patterns

   # Document current usage
   for call in api.call_sites:
       print(f"Called from: {call.parent_function.name}")
       print(f"With args: {[arg.source for arg in call.args]}")
   

2. Make Atomic Changes: Update one aspect at a time

   # First update parameter names
   param.rename("new_name")
   
   # Then update types
   param.type = "new_type"
   
   # Finally update call sites
   for call in api.call_sites:
       # ... update calls
   

3. Maintain Backwards Compatibility:

   # Add new parameter with default
   api.add_parameter("new_param: str = None")
   
   # Later make it required
   api.get_parameter("new_param").remove_default()
   

4. Document Changes:

   # Add clear deprecation messages
   old_api.add_decorator('''@deprecated(
       "Use new_api() instead. Migration guide: docs/migrations/v2.md"
   )''')
   

Remember to test thoroughly after making bulk changes to APIs. While Graph-sitter ensures syntactic correctness, you’ll want to verify the semantic correctness of the changes.