Que fait Mise à niveau et migration AppFolio ?
Aperçu
Les intégrations de gestion immobilière AppFolio dépendent de points d'accès REST versionnés qui évoluent avec la plateforme. Les mises à niveau peuvent renommer des champs sur les objets propriété et locataire, modifier les modèles de pagination, déprécier des points d'accès de bons de travail, et altérer le flux d'authentification de base. Cette compétence détecte votre version actuelle de l'API, mappe les formes de réponse dépréciées vers des remplacements, et effectue un rollback automatique si la nouvelle version échoue.
Prérequis
- Préfixe de version actuelle de l'API documenté (par exemple,
/api/v1/) - Accès au journal des modifications et aux notes de version de l'API AppFolio
- Environnement de staging avec des données de test de propriété et de locataire
- ID client et secret stockés dans des variables d'environnement
- Suite de tests d'intégration existante couvrant les points d'accès principaux
Instructions
- Exécutez la détection de version pour comparer votre version active de l'API avec la dernière.
- Consultez le journal des modifications AppFolio pour les changements cassants entre les deux versions.
- Appliquez les transformations de migration de schéma aux objets de réponse des propriétés et des locataires.
- Mettez à jour les URLs des points d'accès de l'ancien préfixe de version vers le nouveau.
- Passez de la pagination offset à la pagination basée sur curseur si requis par la nouvelle version.
- Exécutez la suite de tests de validation contre l'environnement de staging pour vérifier que tous les points d'accès répondent.
- Déployez en production avec la stratégie de rollback activée.
- Surveillez les journaux d'erreurs pour les réponses 410/401 indiquant des étapes de migration manquées.
Résultat
Après une migration réussie, la compétence produit :
- Un objet
VersionInfoconfirmant les versions actuelle, la plus récente et dépréciées - Des objets propriété et locataire transformés correspondant au nouveau schéma
- Résultats des tests de validation pour les points d'accès des propriétés, locataires, bons de travail et comptabilité
- Entrées du journal de rollback si un point d'accès est retombé sur la version précédente
Détection de version
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} is deprecated. Migrate to ${body.latest_version}.`);
}
return { current, latest: body.latest_version, deprecated };
}
Migration de schéma
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 };
}
Stratégie de rollback
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} rejected; falling back to ${fallbackVersion}`);
const fallback = await fetch(`${baseUrl}/api/${fallbackVersion}${path}`, { headers });
if (!fallback.ok) throw new Error(`Fallback failed: ${fallback.status}`);
return fallback.json();
}
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
return res.json();
}
Exemples
// Detect version and migrate if needed
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);
}
Gestion des erreurs
| Problème de migration | Symptôme | Correctif |
|---|---|---|
| Préfixe de version déprécié | 410 Gone sur chaque requête | Mettre à jour l'URL de base avec le préfixe de la dernière version |
| Champs de propriété renommés | Valeurs undefined dans la synchronisation des propriétés | Appliquer la transformation migrateProperty |
| Pagination offset supprimée | Ensembles de résultats vides après la première page | Passer à la pagination basée sur curseur |
| En-tête d'authentification rejeté | 401 Unauthorized après la mise à niveau | Régénérer le secret client, mettre à jour les variables d'environnement |
| Changement de structure du webhook | Erreurs d'analyse du gestionnaire d'événements | Mettre à jour l'analyseur de charge utile pour la nouvelle structure |
Ressources
- API Stack AppFolio
- Blog technique AppFolio
- Voir
appfolio-ci-integrationpour la validation CI post-migration