/api-integration-patterns

name: api-integration-patterns
description: "Subprocess safety, GitHub CLI integration, retry logic, authentication, rate limiting, and timeout handling. Use when integrating external APIs or CLI tools. TRIGGER when: subprocess, gh cli, API call, retry logic, rate limiting, authentication. DO NOT TRIGGER when: internal function calls, pure Python logic, config file edits."
allowed-tools: [Read]

API Integration Patterns Skill

Standardized patterns for integrating external APIs and CLI tools in the autonomous-dev plugin ecosystem. Focuses on safety, reliability, and security when calling external services.

When This Skill Activates

• Integrating external APIs (GitHub, etc.)
• Executing subprocess commands safely
• Implementing retry logic
• Handling authentication
• Managing rate limits
• Keywords: "api", "subprocess", "github", "gh cli", "retry", "authentication"

---

Core Patterns

1. Subprocess Safety (CWE-78 Prevention)

**Definition**: Execute external commands safely without command injection vulnerabilities.

**Critical Rules**:

• ✅ ALWAYS use argument arrays: `["gh", "issue", "create"]`
• ❌ NEVER use shell=True with user input
• ✅ ALWAYS whitelist allowed commands
• ✅ ALWAYS set timeouts

**Pattern**:

import subprocess
from typing import List

def safe_subprocess(
    command: List[str],
    *,
    allowed_commands: List[str],
    timeout: int = 30
) -> subprocess.CompletedProcess:
    """Execute subprocess with CWE-78 prevention.

    Args:
        command: Command and arguments as list (NOT string!)
        allowed_commands: Whitelist of allowed commands
        timeout: Maximum execution time in seconds

    Returns:
        Completed subprocess result

    Raises:
        SecurityError: If command not in whitelist
        subprocess.TimeoutExpired: If timeout exceeded

    Security:
        - CWE-78 Prevention: Argument arrays (no shell injection)
        - Command Whitelist: Only approved commands
        - Timeout: DoS prevention

    Example:
        >>> result = safe_subprocess(
        ...     ["gh", "issue", "create", "--title", user_title],
        ...     allowed_commands=["gh", "git"]
        ... )
    """
    # Whitelist validation
    if command[0] not in allowed_commands:
        raise SecurityError(f"Command not allowed: {command[0]}")

    # Execute with argument array (NEVER shell=True!)
    return subprocess.run(
        command,
        capture_output=True,
        text=True,
        timeout=timeout,
        check=True,
        shell=False  # CRITICAL
    )

**See**: `docs/subprocess-safety.md`, `examples/safe-subprocess-example.py`

---

2. GitHub CLI (gh) Integration

**Definition**: Standardized patterns for GitHub operations via gh CLI.

**Pattern**:

def create_github_issue(
    title: str,
    body: str,
    *,
    labels: Optional[List[str]] = None,
    timeout: int = 30
) -> str:
    """Create GitHub issue using gh CLI.

    Args:
        title: Issue title
        body: Issue body (markdown)
        labels: Issue labels (default: None)
        timeout: Command timeout in seconds

    Returns:
        Issue URL

    Raises:
        subprocess.CalledProcessError: If gh command fails
        RuntimeError: If gh CLI not installed

    Example:
        >>> url = create_github_issue(
        ...     "Bug: Login fails",
        ...     "Login button doesn't work",
        ...     labels=["bug", "p1"]
        ... )
    """
    # Build gh command (argument array)
    cmd = ["gh", "issue", "create", "--title", title, "--body", body]

    if labels:
        for label in labels:
            cmd.extend(["--label", label])

    # Execute safely
    result = subprocess.run(
        cmd,
        capture_output=True,
        text=True,
        timeout=timeout,
        check=True,
        shell=False
    )

    # Extract URL from output
    return result.stdout.strip()

**See**: `docs/github-cli-integration.md`, `examples/github-issue-example.py`

---

3. Retry Logic with Exponential Backoff

**Definition**: Automatically retry failed API calls with exponential backoff.

**Pattern**:

import time
from typing import Callable, TypeVar, Any

T = TypeVar('T')

def retry_with_backoff(
    func: Callable[..., T],
    *,
    max_attempts: int = 3,
    base_delay: float = 1.0,
    max_delay: float = 60.0
) -> T:
    """Retry function with exponential backoff.

    Args:
        func: Function to retry
        max_attempts: Maximum retry attempts
        base_delay: Initial delay in seconds
        max_delay: Maximum delay in seconds

    Returns:
        Function result

    Raises:
        Exception: Last exception if all retries fail

    Example:
        >>> result = retry_with_backoff(
        ...     lambda: api_call(),
        ...     max_attempts=5,
        ...     base_delay=2.0
        ... )
    """
    last_exception = None

    for attempt in range(max_attempts):
        try:
            return func()
        except Exception as e:
            last_exception = e

            if attempt < max_attempts - 1:
                # Exponential backoff: 1s, 2s, 4s, 8s, ...
                delay = min(base_delay * (2 ** attempt), max_delay)
                time.sleep(delay)

    raise last_exception

**See**: `docs/retry-logic.md`, `templates/retry-decorator-template.py`

---

4. Authentication Patterns

**Definition**: Secure handling of API credentials and tokens.

**Principles**:

• Use environment variables for credentials
• Never hardcode API keys
• Never log credentials
• Validate credentials before use

**Pattern**:

import os
from typing import Optional

def get_github_token() -> str:
    """Get GitHub token from environment.

    Returns:
        GitHub personal access token

    Raises:
        RuntimeError: If token not found

    Security:
        - Environment Variables: Never hardcode tokens
        - Validation: Check token format
        - No Logging: Never log credentials
    "