Was macht AppFolio Upgrade & Migration?
Übersicht
AppFolio Property-Management-Integrationen basieren auf versionierten REST-API-Endpunkten, die sich mit der Plattform weiterentwickeln. Upgrades können Felder in Property- und Tenant-Objekten umbenennen, Paginierungsmodelle ändern, Work-Order-Endpunkte als veraltet markieren und den Basic-Auth-Ablauf verändern. Diese Fähigkeit erkennt Ihre aktuelle API-Version, ordnet veraltete Antwortstrukturen Ersetzungen zu und führt automatisch einen Rollback durch, wenn die neue Version fehlschlägt.
Voraussetzungen
- Aktuelles API-Versionspräfix dokumentiert (z.B.
/api/v1/) - Zugriff auf das AppFolio API-Änderungsprotokoll und die Release-Notes
- Staging-Umgebung mit Test-Property- und Tenant-Daten
- Client-ID und Secret in Umgebungsvariablen gespeichert
- Vorhandene Integrationstestsuite, die Kernendpunkte abdeckt
Anleitung
- Führen Sie die Versionserkennung aus, um Ihre aktive API-Version mit der neuesten zu vergleichen.
- Überprüfen Sie das AppFolio-Änderungsprotokoll auf Breaking Changes zwischen den beiden Versionen.
- Wenden Sie Schema-Migrationstransformationen auf Property- und Tenant-Antwortobjekte an.
- Aktualisieren Sie die Endpunkt-URLs vom alten auf das neue Versionspräfix.
- Wechseln Sie bei Bedarf von Offset- zu Cursor-basierter Paginierung, sofern von der neuen Version gefordert.
- Führen Sie die Smoke-Testsuite gegen Staging aus, um zu überprüfen, ob alle Endpunkte antworten.
- Stellen Sie mit aktivierter Rollback-Strategie in der Produktion bereit.
- Überwachen Sie die Fehlerlogs auf 410/401-Antworten, die auf fehlende Migrationsschritte hinweisen.
Ausgabe
Nach einer erfolgreichen Migration erzeugt die Fähigkeit:
- Ein
VersionInfo-Objekt, das die aktuelle, neueste und veralteten Versionen bestätigt - Transformierte Property- und Tenant-Objekte, die dem neuen Schema entsprechen
- Smoke-Testergebnisse für Property-, Tenant-, Work-Order- und Buchhaltungsendpunkte
- Rollback-Logeinträge, falls ein Endpunkt auf die vorherige Version zurückgefallen ist
Versionserkennung
interface VersionInfo { current: string; latest: string; deprecated: string[]; }
async function detectApiVersion(baseUrl: string, headers: Record<string, string>): Promise<VersionInfo> {
const res = await fetch(`${baseUrl}/api/status`, { headers });
const body = await res.json();
const current = res.headers.get("X-AppFolio-Api-Version") ?? body.api_version;
const deprecated: string[] = body.deprecated_versions ?? [];
if (deprecated.includes(current)) {
console.warn(`Version ${current} ist veraltet. Migrieren Sie zu ${body.latest_version}.`);
}
return { current, latest: body.latest_version, deprecated };
}
Schema-Migration
interface LegacyProperty { address_line1: string; unit_count: number; mgr_id: string; }
interface CurrentProperty { street_address: string; total_units: number; manager_id: string; }
function migrateProperty(old: LegacyProperty): CurrentProperty {
return { street_address: old.address_line1, total_units: old.unit_count, manager_id: old.mgr_id };
}
interface LegacyTenant { lease_end: string; balance_due: number; }
interface CurrentTenant { lease_expiry_date: string; outstanding_balance: number; }
function migrateTenant(old: LegacyTenant): CurrentTenant {
return { lease_expiry_date: old.lease_end, outstanding_balance: old.balance_due };
}
Rollback-Strategie
async function versionAwareRequest(
baseUrl: string, path: string, headers: Record<string, string>,
targetVersion: string, fallbackVersion: string
): Promise<any> {
const res = await fetch(`${baseUrl}/api/${targetVersion}${path}`, { headers });
if (res.status === 410 || res.status === 404) {
console.warn(`${targetVersion} abgelehnt; Rückfall auf ${fallbackVersion}`);
const fallback = await fetch(`${baseUrl}/api/${fallbackVersion}${path}`, { headers });
if (!fallback.ok) throw new Error(`Rückfall fehlgeschlagen: ${fallback.status}`);
return fallback.json();
}
if (!res.ok) throw new Error(`Anfrage fehlgeschlagen: ${res.status}`);
return res.json();
}
Beispiele
// Version erkennen und bei Bedarf migrieren
const info = await detectApiVersion("https://acme.appfolio.com", authHeaders);
if (info.deprecated.includes(info.current)) {
const oldProps = await fetchLegacyProperties();
const migrated = oldProps.map(migrateProperty);
await smokeTestEndpoints("https://acme.appfolio.com", authHeaders);
}
Fehlerbehandlung
| Migrationsproblem | Symptom | Lösung |
|---|---|---|
| Veraltetes Versionspräfix | 410 Gone bei jeder Anfrage | Basis-URL auf neuestes Versionspräfix aktualisieren |
| Umbenannte Property-Felder | undefined-Werte in der Property-Synchronisation | migrateProperty-Transformation anwenden |
| Entfernter Paginierungs-Offset | Leere Ergebnismengen nach Seite eins | Auf Cursor-basierte Paginierung umstellen |
| Abgelehnter Auth-Header | 401 Unauthorized nach Upgrade | Client-Secret neu generieren, Umgebungsvariablen aktualisieren |
| Webhook-Envelope-Änderung | Event-Handler-Parsefehler | Payload-Parser für neuen Envelope aktualisieren |
Ressourcen
- AppFolio Stack APIs
- AppFolio Engineering Blog
- Siehe
appfolio-ci-integrationfür die Post-Migration-CI-Validierung