Communitygithub.com

Mise à niveau et migration AppFolio

Migrer entre les versions de l'API AppFolio et gérer les changements de points d'accès.

Qu'est-ce que Mise à niveau et migration AppFolio ?

Cette compétence automatise la migration entre les versions de l'API REST AppFolio, en détectant la version actuelle, en appliquant des transformations de schéma, et en mettant à jour les URLs des points d'accès. Elle gère les changements tels que les renommages de champs, le passage du pagination offset à cursor, et les dépréciations de points d'accès. La compétence inclut une stratégie de rollback automatique si la nouvelle version échoue, ce qui minimise les risques de régression. Elle est conçue pour les intégrations de gestion immobilière AppFolio, supporte TypeScript et peut être intégrée dans un pipeline CI. L'utilisateur déclenche la migration avec la commande 'appfolio upgrade'.

Compatible avec✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/jeremylongshore/tons-of-skills-marketplace/tree/HEAD/plugins/saas-packs/appfolio-pack/skills/appfolio-upgrade-migration

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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

  1. Exécutez la détection de version pour comparer votre version active de l'API avec la dernière.
  2. Consultez le journal des modifications AppFolio pour les changements cassants entre les deux versions.
  3. Appliquez les transformations de migration de schéma aux objets de réponse des propriétés et des locataires.
  4. Mettez à jour les URLs des points d'accès de l'ancien préfixe de version vers le nouveau.
  5. Passez de la pagination offset à la pagination basée sur curseur si requis par la nouvelle version.
  6. 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.
  7. Déployez en production avec la stratégie de rollback activée.
  8. 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 VersionInfo confirmant 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 migrationSymptômeCorrectif
Préfixe de version déprécié410 Gone sur chaque requêteMettre à jour l'URL de base avec le préfixe de la dernière version
Champs de propriété renommésValeurs undefined dans la synchronisation des propriétésAppliquer la transformation migrateProperty
Pagination offset suppriméeEnsembles de résultats vides après la première pagePasser à la pagination basée sur curseur
En-tête d'authentification rejeté401 Unauthorized après la mise à niveauRégénérer le secret client, mettre à jour les variables d'environnement
Changement de structure du webhookErreurs d'analyse du gestionnaire d'événementsMettre à jour l'analyseur de charge utile pour la nouvelle structure

Ressources

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

jeremylongshore/tons-of-skills-marketplace

Use when asked to structure a landing page for positioning, plan a conversion-optimized page layout, or design a launch page. Examples: "landing page for product launch", "conversion-optimized layout for SaaS

jeremylongshore/tons-of-skills-marketplace

Use when asked to design growth-optimized landing pages, activation funnel layouts, or experiment-friendly page structures. Examples: "growth-optimized landing", "activation funnel layout", "A/B testable page

jeremylongshore/tons-of-skills-marketplace

Use when asked to structure a landing page, design page layout for conversion, or plan landing page information architecture. Examples: "landing page structure for SaaS", "conversion-optimized layout

jeremylongshore/tons-of-skills-marketplace

Generate polished demo videos from a single prompt. Use when the user asks to create a demo video, product walkthrough, feature showcase, or animated presentation. Trigger with "make a demo video", "create a product video", "demo walkthrough", or "feature showcase video".

jeremylongshore/tons-of-skills-marketplace

Track cryptocurrency portfolio with real-time valuations, allocation analysis, and P&L tracking. Use when checking portfolio value, viewing holdings breakdown, analyzing allocations, or exporting portfolio data. Trigger with phrases like "show my portfolio", "check crypto holdings", "portfolio allocation", "track my crypto", or "export portfolio".

jeremylongshore/tons-of-skills-marketplace

Runs the full release workflow for the current project. Commits any uncommitted changes, pushes to remote, creates and merges a PR if on a feature branch, determines the next semver version from conventional commits, creates an annotated git tag and GitHub release with generated notes, cleans up merged branches, and returns to a clean main. Use when the user says promote, ship, release, commit and push, tag and release, or get back to main.

jeremylongshore/tons-of-skills-marketplace

Agent skill at plugins/productivity/content-multiplier/skills/channel-formats/SKILL.md

jeremylongshore/tons-of-skills-marketplace

Operate an evidence-backed editorial queue, balance topic and format coverage, schedule approved drafts, and reconcile backlog state with the publishing system. Use when choosing or scheduling the next blog work. Trigger with "show the editorial calendar" or "pick the next topic".

jeremylongshore/tons-of-skills-marketplace

Configure CI/CD pipeline for AppFolio property management integrations. Trigger: "appfolio CI".

jeremylongshore/tons-of-skills-marketplace

Diagnose and fix common AppFolio API integration errors. Trigger: "appfolio error".

jeremylongshore/tons-of-skills-marketplace

Build property management dashboard with AppFolio API data. Trigger: "appfolio property dashboard".

jeremylongshore/tons-of-skills-marketplace

Automate tenant management and lease operations with AppFolio. Trigger: "appfolio tenant management".

jeremylongshore/tons-of-skills-marketplace

Collect AppFolio API debug evidence for support tickets. Trigger: "appfolio debug".

jeremylongshore/tons-of-skills-marketplace

Deploy AppFolio integration service to cloud infrastructure. Trigger: "deploy appfolio".

jeremylongshore/tons-of-skills-marketplace

Query AppFolio properties, units, and tenants via REST API. Trigger: "appfolio hello world".

jeremylongshore/tons-of-skills-marketplace

Configure AppFolio Stack API authentication with OAuth 2.0. Use when setting up property management API access, registering as an AppFolio Stack partner, or configuring client credentials for API calls. Trigger: "install appfolio", "setup appfolio", "appfolio auth", "appfolio API key".

jeremylongshore/tons-of-skills-marketplace

Set up local development for AppFolio property management API integration. Trigger: "appfolio local dev".

jeremylongshore/tons-of-skills-marketplace

Production readiness checklist for AppFolio integrations. Trigger: "appfolio production checklist".

jeremylongshore/tons-of-skills-marketplace

Handle AppFolio API rate limits with throttling and backoff. Trigger: "appfolio rate limit".

jeremylongshore/tons-of-skills-marketplace

Reference architecture for AppFolio property management integration. Trigger: "appfolio architecture".

Skills associés