bamboohr-upgrade-migration

# BambooHR Upgrade & Migration ## Overview Guide for handling BambooHR API changes, migrating from legacy patterns, and proactively detecting deprecations. BambooHR's API is versioned at v1 — breaking changes are announced on their changelog rather than through version bumps. ## Prerequisites - Current BambooHR integration working - Access to BambooHR API changelog - Git for version control - Test suite available ## Instructions ### Step 1: Check for Announced Changes ```bash # Monitor BambooHR's official changelog pages echo "Check these URLs before any migration work:" echo " Past changes: https://documentation.bamboohr.com/docs/past-changes-to-the-api" echo " Planned changes: https://documentation.bamboohr.com/docs/planned-changes-to-the-api" echo " Status page: https://status.bamboohr.com" ``` ### Step 2: Common Migration Patterns #### URL Format Migration BambooHR has used two base URL formats historically: ```typescript // Legacy format (still works) const LEGACY = `https://api.bamboohr.com/api/gateway.php/${domain}/v1`; // Modern format (equivalent) const MODERN = `https://${domain}.bamboohr.com/api/v1`; // Migration: both work, but use the gateway.php format for API key auth // The modern format is used for browser-based OAuth flows ``` #### XML to JSON Migration ```typescript // Legacy: XML responses (default if no Accept header) const xmlRes = await fetch(`${BASE}/employees/directory`, { headers: { Authorization: AUTH }, // No Accept hea...