AppFolio Lokale Entwicklungsschleife
Überblick
Lokaler Entwicklungsworkflow für die AppFolio Property Management API-Integration. Bietet eine schnelle Feedbackschleife mit Mock-Endpunkten für Property, Tenant und Lease, sodass du Integrationen erstellen und testen kannst, ohne das Live-API-Kontingent zu verbrauchen. Wechsel zwischen Mock-Modus für schnelle Iterationen und Sandbox-Modus für die Vorab-Validierung gegen die echte AppFolio Stack API.
Voraussetzungen
- Eine reine Mock-Umgebung mit synthetischen Property-, Tenant-, Lease- und Work-Order-Fixtures, die keine Produktionsadressen, -namen oder -zahlungen enthalten.
- Ein separat verwaltetes Sandbox-Zugangsdatenpaar und ein genehmigtes Safe-Read-Fixture für die dedizierte Integrationsspur; diese werden niemals vom lokalen Dev-Server geladen.
- Eine Log-Richtlinie, die nur Anfrageform und -status aufzeichnet, sowie einen expliziten Eigentümer für Sandbox-Kontingent, Fixture-Reset und Zugangsdatenrotation.
Anleitung
- Starte den lokalen Server nur im Mock-Modus und führe Lese-/Schreiboperationen gegen synthetische Routen mit deterministischen Fixtures durch.
- Teste Anfragevalidierung, Idempotenz, Redaktion und Fehlerbehandlung in Unit-Tests, bevor irgendeine Sandbox-Konnektivitätsprüfung stattfindet.
- Führe die Sandbox-Spur separat mit dem vertraglich gebundenen verwalteten Client und einem autorisierten Safe-Read-Fixture aus; verwandle keinen lokalen Proxy in einen Live-API-Tunnel.
- Stoppe, wenn das Fixture, die Zugangsdaten, das Anfragebudget oder die Ausgaberedaktion nicht verifiziert sind, korrigiere dann die Umgebung, bevor du fortfährst.
Umgebungseinrichtung
cp .env.example .env
# Lass die Anbieter-Zugangsdaten lokal leer. Mock-Modus ist die Voreinstellung.
# MOCK_MODE=true
npm install express axios dotenv tsx typescript @types/node
npm install -D vitest supertest @types/express
Dev-Server
// src/dev/server.ts
import express from "express";
const app = express();
app.use(express.json());
const MOCK = process.env.MOCK_MODE === "true";
if (!MOCK) throw new Error("Lokaler Server ist nur für Mock; verwende die verwaltete Sandbox-Integrationsspur");
const { mountMockRoutes } = require("./mocks");
mountMockRoutes(app);
app.listen(3001, () => console.log(`AppFolio Dev-Server auf :3001 [mock=${MOCK}]`));
Mock-Modus
// src/dev/mocks.ts — realistische Immobilienverwaltungsantworten
export function mountMockRoutes(app: any) {
app.get("/api/v1/properties", (_req: any, res: any) => res.json([
{ id: "prop_1", name: "Sunset Apartments", address: { street: "123 Sunset Blvd", city: "Los Angeles", state: "CA" }, property_type: "residential", unit_count: 24 },
{ id: "prop_2", name: "Downtown Office", address: { street: "456 Main St", city: "San Francisco", state: "CA" }, property_type: "commercial", unit_count: 8 },
]));
app.get("/api/v1/tenants", (_req: any, res: any) => res.json([
{ id: "t1", first_name: "Jane", last_name: "Smith", email: "[email protected]", unit_id: "u1", lease_id: "l1" },
]));
app.get("/api/v1/leases", (_req: any, res: any) => res.json([
{ id: "l1", unit_id: "u1", start_date: "2025-01-01", end_date: "2026-01-01", rent_amount: 2500, status: "active" },
]));
app.post("/api/v1/work-orders", (req: any, res: any) => res.status(201).json({ id: "wo_1", ...req.body, status: "open" }));
}
Test-Workflow
npm run dev:mock & # Mock-Server im Hintergrund starten
npm run test # Unit-Tests mit vitest
npm run test -- --watch # Watch-Modus für schnelle Iterationen
npm run test:sandbox # Verwaltete, schreibgeschützte Sandbox-Spur
Debug-Tipps
- Setze
DEBUG=express:*, um alle Routenabgleiche und Middleware-Ausführungen zu verfolgen - Verwende lokale Test-Assertions für Fixture-Anzahlen und Schema-Form, nicht rohe Tenant-Payload-Dumps
- Überprüfe den Header
X-RateLimit-Remainingbeim Testen gegen die Live-API - Die AppFolio-Sandbox gibt
403für Properties zurück, die du nicht besitzt – überprüfe deinen API-Key-Bereich - Verwende Interceptors nur für redigierte Endpunkt-/Status-/Zahl-Telemetrie während der Entwicklung
Ausgabe
- Ein deterministischer, reiner Mock-Server mit synthetischen Immobilienverwaltungs-Fixtures und keiner Abhängigkeit von Anbieter-Zugangsdaten
- Unit-Test-Nachweis für Validierung, Idempotenz und PII-sichere Beobachtbarkeit
- Ein separates, verwaltetes Sandbox-Ergebnis, das nur redigierten Safe-Read-Status enthält
Beispiele
Für eine Work-Order-UI-Änderung füge ein synthetisches Mock-Fixture hinzu und teste das Anfrageschema sowie das Verhalten bei doppelten Einsendungen lokal. Bestätige die zurückgegebene ID und den Status, ohne den Anfragekörper oder den Tenant-Datensatz auszugeben. Nach Bestehen der Unit-Tests führe die dedizierte Sandbox-Spur gegen ein genehmigtes Safe-Read-Fixture aus. Wenn der Mock-Modus deaktiviert ist, eine Sandbox-Zugangsdaten lokal erscheinen oder eine Antwort unredigierte Tenant-Felder enthält, stoppe den Lauf und stelle die lokale Grenze wieder her.
Fehlerbehandlung
| Problem | Ursache | Lösung |
|---|---|---|
401 Unauthorized | Ungültiger oder abgelaufener API-Key | Neu im AppFolio Stack Portal generieren |
403 Forbidden | Key hat keinen Bereich für den Endpunkt | Zusätzliche Berechtigungen anfordern |
404 Not Found | Falsche Property-ID oder Pfad | Überprüfen, ob die Ressource in der Sandbox existiert |
429 Too Many Requests | Rate-Limit überschritten | Exponentielles Backoff hinzufügen, Mock-Modus verwenden |
ECONNREFUSED :3001 | Dev-Server läuft nicht | npm run dev:mock zuerst ausführen |
Ressourcen
Nächste Schritte
Siehe appfolio-debug-bundle.