Actualización y Migración de AppFolio
Descripción General
Las integraciones de gestión de propiedades de AppFolio dependen de endpoints REST versionados de la API que evolucionan con la plataforma. Las actualizaciones pueden renombrar campos en objetos de propiedad e inquilino, cambiar modelos de paginación, desaprobar endpoints de órdenes de trabajo y alterar el flujo de autenticación básica. Esta habilidad detecta tu versión actual de la API, mapea formas de respuesta obsoletas a reemplazos y revierte automáticamente si la nueva versión falla.
Prerrequisitos
- Prefijo de versión de API actual documentado (ej.,
/api/v1/) - Acceso al registro de cambios y notas de la versión de la API de AppFolio
- Entorno de staging con datos de prueba de propiedades e inquilinos
- ID de cliente y secreto almacenados en variables de entorno
- Suite de pruebas de integración existente que cubra los endpoints principales
Instrucciones
- Ejecuta la detección de versión para comparar tu versión activa de la API contra la última.
- Revisa el registro de cambios de AppFolio para cambios importantes entre las dos versiones.
- Aplica las transformaciones de migración de esquema a los objetos de respuesta de propiedad e inquilino.
- Actualiza las URL de los endpoints del prefijo de versión antiguo al nuevo.
- Cambia la paginación de desplazamiento a basada en cursor si la nueva versión lo requiere.
- Ejecuta la suite de pruebas de humo contra staging para verificar que todos los endpoints respondan.
- Despliega a producción con la estrategia de reversión habilitada.
- Monitorea los registros de errores para respuestas 410/401 que indiquen pasos de migración omitidos.
Salida
Después de una migración exitosa, la habilidad produce:
- Un objeto
VersionInfoque confirma la versión actual, la última y las obsoletas - Objetos de propiedad e inquilino transformados que coinciden con el nuevo esquema
- Resultados de pruebas de humo para los endpoints de propiedades, inquilinos, órdenes de trabajo y contabilidad
- Entradas de registro de reversión si algún endpoint retrocedió a la versión anterior
Detección de Versión
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 };
}
Migración de Esquema
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 };
}
Estrategia de Reversión
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();
}
Ejemplos
// 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);
}
Manejo de Errores
| Problema de Migración | Síntoma | Solución |
|---|---|---|
| Prefijo de versión obsoleto | 410 Gone en cada solicitud | Actualizar la URL base al prefijo de la última versión |
| Campos de propiedad renombrados | Valores undefined en la sincronización de propiedades | Aplicar la transformación migrateProperty |
| Desplazamiento de paginación eliminado | Conjuntos de resultados vacíos después de la página uno | Cambiar a paginación basada en cursor |
| Encabezado de autenticación rechazado | 401 Unauthorized después de la actualización | Regenerar secreto de cliente, actualizar variables de entorno |
| Cambio en el sobre del webhook | Errores de análisis en el manejador de eventos | Actualizar el analizador de carga útil para el nuevo sobre |
Recursos
- AppFolio Stack APIs
- AppFolio Engineering Blog
- Consulta
appfolio-ci-integrationpara validación de CI posterior a la migración