AppFolio 업그레이드 및 마이그레이션은(는) 무엇을 하나요?
개요
AppFolio 부동산 관리 통합은 플랫폼과 함께 진화하는 버전이 지정된 REST API 엔드포인트에 의존합니다. 업그레이드는 속성(property) 및 임차인(tenant) 객체의 필드 이름을 변경하고, 페이지네이션 모델을 변경하며, 작업 지시(work-order) 엔드포인트를 폐기하고, 기본 인증(basic-auth) 흐름을 변경할 수 있습니다. 이 스킬은 현재 API 버전을 감지하고, 폐기된 응답 형태를 대체 형태로 매핑하며, 새 버전이 실패하면 자동으로 롤백합니다.
사전 조건
- 현재 API 버전 접두사 문서화 (예:
/api/v1/) - AppFolio API 변경 로그(changelog) 및 릴리스 노트에 접근 권한
- 테스트 속성 및 임차인 데이터가 있는 스테이징 환경
- 환경 변수에 저장된 클라이언트 ID 및 시크릿
- 핵심 엔드포인트를 다루는 기존 통합 테스트 스위트
지침
- 버전 감지를 실행하여 활성 API 버전을 최신 버전과 비교합니다.
- AppFolio 변경 로그에서 두 버전 간의 호환성을 깨는 변경 사항(Breaking Changes)을 검토합니다.
- 속성 및 임차인 응답 객체에 스키마 마이그레이션 변환을 적용합니다.
- 엔드포인트 URL을 이전 버전 접두사에서 새 버전 접두사로 업데이트합니다.
- 새 버전에서 필요한 경우 페이지네이션을 오프셋(offset)에서 커서(cursor) 기반으로 전환합니다.
- 스테이징 환경에서 스모크 테스트 스위트를 실행하여 모든 엔드포인트가 응답하는지 확인합니다.
- 롤백 전략을 활성화한 상태로 프로덕션에 배포합니다.
- 마이그레이션 단계를 놓쳤음을 나타내는 410/401 응답에 대한 오류 로그를 모니터링합니다.
출력
성공적인 마이그레이션 후 스킬은 다음을 생성합니다:
- 현재, 최신 및 폐기된 버전을 확인하는
VersionInfo객체 - 새 스키마와 일치하도록 변환된 속성 및 임차인 객체
- 속성, 임차인, 작업 지시 및 회계 엔드포인트에 대한 스모크 테스트 결과
- 모든 엔드포인트가 이전 버전으로 대체된 경우 롤백 로그 항목
버전 감지
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(`버전 ${current}이(가) 폐기되었습니다. ${body.latest_version}(으)로 마이그레이션하세요.`);
}
return { current, latest: body.latest_version, deprecated };
}
스키마 마이그레이션
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 };
}
롤백 전략
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}이(가) 거부되었습니다. ${fallbackVersion}(으)로 대체합니다.`);
const fallback = await fetch(`${baseUrl}/api/${fallbackVersion}${path}`, { headers });
if (!fallback.ok) throw new Error(`대체 실패: ${fallback.status}`);
return fallback.json();
}
if (!res.ok) throw new Error(`요청 실패: ${res.status}`);
return res.json();
}
예시
// 버전을 감지하고 필요한 경우 마이그레이션
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);
}
오류 처리
| 마이그레이션 문제 | 증상 | 수정 방법 |
|---|---|---|
| 폐기된 버전 접두사 | 모든 요청에 410 Gone 발생 | 기본 URL을 최신 버전 접두사로 업데이트 |
| 이름이 변경된 속성 필드 | 속성 동기화에서 undefined 값 발생 | migrateProperty 변환 적용 |
| 제거된 페이지네이션 오프셋 | 첫 페이지 이후 빈 결과 세트 | 커서 기반 페이지네이션으로 전환 |
| 인증 헤더 거부됨 | 업그레이드 후 401 Unauthorized 발생 | 클라이언트 시크릿 재생성, 환경 변수 업데이트 |
| 웹훅 페이로드 변경 | 이벤트 핸들러 파싱 오류 발생 | 새 페이로드 형식에 맞게 파서 업데이트 |
리소스
- AppFolio Stack APIs
- AppFolio Engineering Blog
- 마이그레이션 후 CI 검증은
appfolio-ci-integration참조