Was macht AppFolio SDK Patterns?
Übersicht
Produktionsreife Muster für die AppFolio REST-API zur Immobilienverwaltung. AppFolio verwendet HTTP Basic Auth mit Client-Anmeldedaten und gibt JSON-Antworten für Immobilien, Mieter, Mietverträge und Arbeitsaufträge zurück. Ein strukturierter Singleton-Client verhindert die Streuung von Anmeldedaten, erzwingt eine konsistente Fehlerbehandlung und zentralisiert die Paginierungslogik über alle Endpunkte der Immobilienverwaltung.
Voraussetzungen
- Eine vom Anbieter verifizierte Basis-URL, Authentifizierungsmethode, Endpunkt-Bereich und verwalteter Pfad zur Injektion von Geheimnissen für das Zielportfolio.
- Schema-Validierung, Anforderungs-Timeout, endpointspezifische Rate-Limits und Idempotenz-Schlüssel für alle änderungsfähigen Dienstmethoden.
- Synthetische Testdaten für Unit-Tests; Produktionsdaten für Mieter, Mietverträge und Zahlungen dürfen nicht als Standard-Mock-, Log- oder Fehlermeldungsinhalt verwendet werden.
Anleitung
- Erstellen Sie einen vertragsgebundenen Client pro Laufzeit und lehnen Sie fehlende oder ungültige Konfiguration ab, bevor Anfragen gestartet werden.
- Validieren Sie Abfragegrenzen und Antwortstrukturen an der Dienstgrenze und übergeben Sie nur minimierte, typisierte Felder an die Aufrufer.
- Geben Sie einen klassifizierten
429- oder unbekannten Schreibfehler an den Aufrufer zurück; wiederholen Sie nur idempotente Operationen, nachdem der Aufrufer den Cursor/Schlüssel und die Verzögerung aufgezeichnet hat. - Halten Sie Schreib-Workflows hinter expliziten Autorisierungs-, Prüf- und Abgleichskontrollen, anstatt sie in generische SDK-Hilfsprogramme einzubetten.
Singleton-Client
import axios, { AxiosInstance } from 'axios';
let _client: AxiosInstance | null = null;
export function getClient(): AxiosInstance {
if (!_client) {
const clientId = process.env.APPFOLIO_CLIENT_ID;
const clientSecret = process.env.APPFOLIO_CLIENT_SECRET;
const baseURL = process.env.APPFOLIO_BASE_URL;
if (!clientId || !clientSecret || !baseURL) throw new Error('APPFOLIO_CLIENT_ID, SECRET, and BASE_URL required');
_client = axios.create({ baseURL, auth: { username: clientId, password: clientSecret }, timeout: 30000 });
}
return _client;
}
Fehler-Wrapper
export class AppFolioError extends Error {
constructor(public status: number, public code: string, message: string) { super(message); }
}
export async function safeCall<T>(operation: string, fn: () => Promise<T>): Promise<T> {
try { return await fn(); }
catch (err: any) {
const status = err.response?.status ?? 0;
if (status === 429) {
const retryAfter = err.response?.headers?.['retry-after'];
throw new AppFolioError(429, 'RATE_LIMIT', `Wiederholung nach ${retryAfter ?? 'vom Anbieter festgelegter Verzögerung'}; unbekannten Schreibvorgang nicht automatisch wiederholen`);
}
if (status === 401) throw new AppFolioError(401, 'AUTH', 'Ungültige APPFOLIO_CLIENT_ID oder SECRET');
throw new AppFolioError(status, 'API_ERROR', `${operation} fehlgeschlagen [${status}]: ${err.message}`);
}
}
Anfrage-Builder
class AppFolioQuery {
private params: Record<string, string> = {};
status(s: 'active' | 'past' | 'future') { this.params.status = s; return this; }
propertyId(id: string) { this.params.property_id = id; return this; }
page(n: number) { this.params.page = String(n); return this; }
perPage(n: number) { this.params.per_page = String(Math.min(n, 200)); return this; }
since(date: string) { this.params.updated_since = date; return this; }
build() { return this.params; }
}
// Verwendung: new AppFolioQuery().status('active').perPage(50).build();
Antworttypen
interface Property {
id: string; name: string; property_type: 'residential' | 'commercial' | 'mixed';
address: { street: string; city: string; state: string; zip: string };
unit_count: number; status: string;
}
interface Tenant {
id: string; first_name: string; last_name: string;
email: string; phone: string; unit_id: string; lease_id: string;
}
interface Lease {
id: string; unit_id: string; tenant_id: string;
start_date: string; end_date: string; rent_amount: number; status: 'active' | 'expired' | 'future';
}
interface WorkOrder {
id: string; property_id: string; unit_id: string;
description: string; priority: 'low' | 'medium' | 'high' | 'emergency';
status: 'open' | 'in_progress' | 'completed';
}
Test-Hilfsprogramme
export function mockProperty(overrides: Partial<Property> = {}): Property {
return { id: 'prop-001', name: 'Maple Ridge Apts', property_type: 'residential',
address: { street: '100 Main St', city: 'Austin', state: 'TX', zip: '78701' },
unit_count: 24, status: 'active', ...overrides };
}
export function mockLease(overrides: Partial<Lease> = {}): Lease {
return { id: 'lease-001', unit_id: 'unit-001', tenant_id: 'ten-001',
start_date: '2025-01-01', end_date: '2026-01-01', rent_amount: 1500, status: 'active', ...overrides };
}
Fehlerbehandlung
| Muster | Verwendung | Beispiel |
|---|---|---|
safeCall-Wrapper | Alle API-Aufrufe | Verhindert, dass unbehandelte 4xx/5xx Flows zum Absturz bringen |
| Aufrufergesteuerte Wiederholung bei 429 | Ratelimitierte idempotente Batch-Lesevorgänge | Cursor/Schlüssel bewahren, Retry-After beachten, dann bewusst wiederholen |
| Auth-Validierung | Client-Initialisierung | Wirft frühzeitig einen Fehler, wenn Anmeldedaten fehlen |
| Paginierungsschleife | Auflisten von Immobilien/Mietern | page erhöhen, bis leere Antwort |
Ausgabe
- Ein validierter, vertragsgebundener API-Client mit zentralisiertem Timeout und Fehlerklassifizierungsverhalten
- Begrenzte Abfrageparameter und minimierte typisierte Antworten für Dienstaufrufer
- Explizite Rate-Limit- und unbekannte Schreibausgaben, die aufrufergesteuerte Cursor-/Idempotenz-/Abgleichsentscheidungen erfordern
Beispiele
Erstellen Sie für einen Lesevorgang einer Immobilienliste eine Abfrage mit einer begrenzten Seitengröße, führen Sie sie durch safeCall aus und überprüfen Sie die zurückgegebenen Immobilien-IDs und die Anzahl anhand eines synthetischen Testdatensatzes. Für eine Mutation persistieren Sie einen Idempotenz-Schlüssel vor dem Absenden und behandeln Sie einen Timeout oder 429 als Pausen-/Abgleichsbedingung, anstatt die Funktion erneut aufzurufen. Wenn Client-Konfiguration, Antwortstruktur oder Schreibergebnis nicht verifiziert sind, stoppen Sie den Workflow und melden Sie einen geschwärzten Fehler an den Eigentümer.
Ressourcen
Nächste Schritte
Wenden Sie die Muster in appfolio-core-workflow-a an.