Boucle de développement local AppFolio
Aperçu
Workflow de développement local pour l'intégration de l'API de gestion immobilière AppFolio. Offre une boucle de rétroaction rapide avec des points de terminaison simulés (propriétés, locataires, baux) afin de construire et tester des intégrations sans consommer de quota API réel. Basculez entre le mode mock pour des itérations rapides et le mode sandbox pour une validation pré-déploiement contre l'API AppFolio Stack réelle.
Prérequis
- Un environnement local mock-only avec des jeux de données synthétiques de propriétés, locataires, baux et ordres de travaux ne contenant aucune adresse, nom ou paiement de production.
- Un identifiant sandbox géré séparément et un jeu de données sécurisé en lecture seule approuvé pour la voie d'intégration dédiée ; il n'est jamais chargé par le serveur de développement local.
- Une politique de journalisation qui enregistre uniquement la forme et le statut de la requête, ainsi qu'un propriétaire explicite pour le quota sandbox, la réinitialisation des jeux de données et la rotation des identifiants.
Instructions
- Lancez le serveur local uniquement en mode mock et effectuez des lectures/écritures sur des routes synthétiques avec des jeux de données déterministes.
- Testez la validation des requêtes, l'idempotence, la rédaction et la gestion des erreurs dans les tests unitaires avant toute vérification de connectivité sandbox.
- Exécutez la voie sandbox séparément avec le client géré lié par contrat et un seul jeu de données sécurisé en lecture seule autorisé ; ne transformez pas un proxy local en tunnel API live.
- Arrêtez-vous lorsque le jeu de données, les identifiants, le budget de requêtes ou la rédaction des sorties ne sont pas vérifiés, puis corrigez l'environnement avant de continuer.
Configuration de l'environnement
cp .env.example .env
# Laissez les identifiants du fournisseur vides en local. Le mode mock est le mode par défaut.
# MOCK_MODE=true
npm install express axios dotenv tsx typescript @types/node
npm install -D vitest supertest @types/express
Serveur de développement
// 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("Le serveur local est mock-only ; utilisez la voie d'intégration sandbox gérée");
const { mountMockRoutes } = require("./mocks");
mountMockRoutes(app);
app.listen(3001, () => console.log(`Serveur de développement AppFolio sur :3001 [mock=${MOCK}]`));
Mode Mock
// src/dev/mocks.ts — réponses réalistes de gestion immobilière
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" }));
}
Workflow de test
npm run dev:mock & # Lance le serveur mock en arrière-plan
npm run test # Tests unitaires avec vitest
npm run test -- --watch # Mode surveillance pour itérations rapides
npm run test:sandbox # Voie sandbox gérée en lecture seule
Conseils de débogage
- Définissez
DEBUG=express:*pour tracer tout le routage et l'exécution des middlewares - Utilisez des assertions de test locales pour les comptes de jeux de données et la forme du schéma, pas les vidages bruts de données de locataires
- Vérifiez l'en-tête
X-RateLimit-Remaininglors des tests contre l'API live - Le sandbox AppFolio renvoie
403pour les propriétés que vous ne possédez pas — vérifiez la portée de votre clé API - Utilisez des intercepteurs uniquement pour la télémétrie de point de terminaison/statut/comptage lors du développement
Résultat
- Un serveur local mock-only déterministe avec des jeux de données synthétiques de gestion immobilière et aucune dépendance aux identifiants du fournisseur
- Preuve de test unitaire pour la validation, l'idempotence et l'observabilité sans PII
- Un résultat sandbox géré séparé contenant uniquement un statut de lecture sécurisée rédigé
Exemples
Pour un changement d'interface utilisateur d'ordre de travail, ajoutez un jeu de données synthétique mock et testez le schéma de la requête ainsi que le comportement de soumission en double localement. Affirmez l'ID et le statut renvoyés sans émettre le corps de la requête ni l'enregistrement du locataire. Une fois les tests unitaires réussis, exécutez la voie sandbox dédiée sur un seul jeu de données sécurisé en lecture seule approuvé. Si le mode mock est désactivé, qu'un identifiant sandbox apparaît localement, ou qu'une réponse contient des champs de locataires non rédigés, arrêtez l'exécution et restaurez la frontière locale.
Gestion des erreurs
| Problème | Cause | Solution |
|---|---|---|
401 Unauthorized | Clé API invalide ou expirée | Régénérez-la sur le portail AppFolio Stack |
403 Forbidden | La clé manque de portée pour le point de terminaison | Demandez des autorisations supplémentaires |
404 Not Found | Mauvais ID de propriété ou chemin | Vérifiez que la ressource existe dans le sandbox |
429 Too Many Requests | Limite de débit dépassée | Ajoutez un backoff exponentiel, utilisez le mode mock |
ECONNREFUSED :3001 | Le serveur de développement ne tourne pas | Exécutez npm run dev:mock d'abord |
Ressources
Prochaines étapes
Consultez appfolio-debug-bundle.