Atualização e Migração do AppFolio
Visão Geral
As integrações de gerenciamento de propriedades do AppFolio dependem de endpoints REST versionados que evoluem com a plataforma. As atualizações podem renomear campos em objetos de propriedade e inquilino, alterar modelos de paginação, descontinuar endpoints de ordens de serviço e modificar o fluxo de autenticação básica. Esta skill detecta sua versão atual da API, mapeia formas de resposta obsoletas para suas substituições e reverte automaticamente caso a nova versão falhe.
Pré-requisitos
- Prefixo da versão atual da API documentado (ex.:
/api/v1/) - Acesso ao changelog e notas de versão da API do AppFolio
- Ambiente de staging com dados de teste de propriedade e inquilino
- ID do cliente e segredo armazenados em variáveis de ambiente
- Suite de testes de integração existente que cobre endpoints principais
Instruções
- Execute a detecção de versão para comparar sua versão ativa da API com a mais recente.
- Revise o changelog do AppFolio para alterações significativas entre as duas versões.
- Aplique as transformações de migração de esquema nos objetos de resposta de propriedade e inquilino.
- Atualize as URLs dos endpoints do prefixo de versão antigo para o novo.
- Altere a paginação de offset para cursor, se exigido pela nova versão.
- Execute a suite de testes de fumaça contra o staging para verificar se todos os endpoints respondem.
- Implante em produção com a estratégia de rollback habilitada.
- Monitore logs de erro para respostas 410/401 que indiquem etapas de migração perdidas.
Saída
Após uma migração bem-sucedida, a skill produz:
- Um objeto
VersionInfoconfirmando as versões atual, mais recente e obsoletas - Objetos de propriedade e inquilino transformados de acordo com o novo esquema
- Resultados dos testes de fumaça para endpoints de propriedades, inquilinos, ordens de serviço e contabilidade
- Entradas de log de rollback se algum endpoint retrocedeu para a versão anterior
Detecção de Versão
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 };
}
Migração 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 };
}
Estratégia 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();
}
Exemplos
// 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);
}
Tratamento de Erros
| Problema de Migração | Sintoma | Correção |
|---|---|---|
| Prefixo de versão obsoleto | 410 Gone em toda requisição | Atualizar URL base para o prefixo da versão mais recente |
| Campos de propriedade renomeados | Valores undefined na sincronização de propriedades | Aplicar transformação migrateProperty |
| Offset de paginação removido | Conjuntos de resultados vazios após a primeira página | Mudar para paginação baseada em cursor |
| Cabeçalho de autenticação rejeitado | 401 Unauthorized após atualização | Regenerar segredo do cliente, atualizar variáveis de ambiente |
| Alteração no envelope do webhook | Erros de análise no manipulador de eventos | Atualizar parser de payload para novo envelope |
Recursos
- AppFolio Stack APIs
- AppFolio Engineering Blog
- Consulte
appfolio-ci-integrationpara validação de CI pós-migração