AppFolio ローカル開発ループ
概要
AppFolio 物件管理API統合のためのローカル開発ワークフローです。モックの物件、テナント、リースエンドポイントを使用して迅速なフィードバックループを提供し、ライブAPIクォータを消費せずに統合の構築とテストを行えます。迅速な反復開発にはモックモード、デプロイ前の検証用にはサンドボックスモードを切り替えて使用できます。
前提条件
- 本番の住所、名前、支払い情報を含まない、合成の物件、テナント、リース、作業指示書フィクスチャを使用するモックのみのローカル環境。
- 別途管理されるサンドボックス認証情報と、専用統合レーン用の承認済みセーフリードフィクスチャ。これはローカル開発サーバーからは読み込まれません。
- リクエストの形状とステータスのみを記録するログポリシーと、サンドボックス割り当て、フィクスチャリセット、認証情報ローテーションのための明示的な所有者が必要です。
手順
- ローカルサーバーをモックモードでのみ起動し、決定論的なフィクスチャを使用して合成ルートに対して読み書き操作を実行します。
- サンドボックス接続確認の前に、単体テストでリクエストバリデーション、冪等性、編集、エラーハンドリングをテストします。
- サンドボックスレーンは、契約に基づく管理クライアントと1つの承認済みセーフリードフィクスチャを使用して別途実行します。ローカルプロキシをライブAPIトンネルに変換しないでください。
- フィクスチャ、認証情報、リクエスト予算、出力編集が未確認の場合は停止し、環境を修正してから続行します。
環境設定
cp .env.example .env
# ローカルではプロバイダ認証情報は空白のままにしてください。モックモードがデフォルトです。
# MOCK_MODE=true
npm install express axios dotenv tsx typescript @types/node
npm install -D vitest supertest @types/express
開発サーバー
// 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("ローカルサーバーはモックのみです。管理サンドボックス統合レーンを使用してください。");
const { mountMockRoutes } = require("./mocks");
mountMockRoutes(app);
app.listen(3001, () => console.log(`AppFolio 開発サーバー on :3001 [mock=${MOCK}]`));
モックモード
// src/dev/mocks.ts — 実際の物件管理レスポンス
import express from "express";
export function mountMockRoutes(app: express.Application) {
app.get("/api/v1/properties", (_req, res) => res.json([
{ id: "prop_1", name: "サンセットアパートメント", address: { street: "123 Sunset Blvd", city: "Los Angeles", state: "CA" }, property_type: "residential", unit_count: 24 },
{ id: "prop_2", name: "ダウンタウンオフィス", address: { street: "456 Main St", city: "San Francisco", state: "CA" }, property_type: "commercial", unit_count: 8 },
]));
app.get("/api/v1/tenants", (_req, res) => 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, res) => 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, res) => res.status(201).json({ id: "wo_1", ...req.body, status: "open" }));
}
テストワークフロー
npm run dev:mock & # バックグラウンドでモックサーバーを起動
npm run test # vitest で単体テスト
npm run test -- --watch # ウォッチモードで迅速な反復
npm run test:sandbox # 管理された読み取り専用サンドボックスレーン
デバッグのヒント
DEBUG=express:*を設定してすべてのルートマッチングとミドルウェア実行をトレース- テストアサーションには未加工のテナントペイロードダンプではなく、フィクスチャ数とスキーマ形状を使用
- ライブAPIに対してテストする際は、
X-RateLimit-Remainingヘッダーを確認 - AppFolio サンドボックスは、自分が所有していないプロパティに対して
403を返します – APIキーのスコープを確認 - 開発中は、編集されたエンドポイント/ステータス/カウントのテレメトリーにのみインターセプターを使用
出力
- 合成の物件管理フィクスチャを使用し、プロバイダ認証情報に依存しない、決定論的なモックのみのローカルサーバー
- バリデーション、冪等性、PIIセーフな可観測性のための単体テスト証跡
- 編集されたセーフリードステータスのみを含む、別の管理サンドボックス結果
例
作業指示書UIの変更を行う場合、合成モックフィクスチャを追加し、ローカルでリクエストスキーマと重複送信動作をテストします。リクエストボディやテナントレコードを出力せずに、返されたIDとステータスをアサートします。単体テストが合格したら、専用サンドボックスレーンを1つの承認済みセーフリードフィクスチャに対して実行します。モックモードが無効になっている場合、ローカルにサンドボックス認証情報が表示される場合、またはレスポンスに編集されていないテナントフィールドが含まれている場合は、実行を停止してローカル境界を復元します。
エラーハンドリング
| 問題 | 原因 | 修正方法 |
|---|---|---|
401 Unauthorized | 無効または期限切れのAPIキー | AppFolio Stack ポータルで再生成 |
403 Forbidden | キーにエンドポイントのスコープがない | 追加の権限をリクエスト |
404 Not Found | 間違ったプロパティIDまたはパス | リソースがサンドボックスに存在することを確認 |
429 Too Many Requests | レート制限超過 | 指数バックオフを追加、モックモードを使用 |
ECONNREFUSED :3001 | 開発サーバーが起動していない | 最初に npm run dev:mock を実行 |
リソース
次のステップ
appfolio-debug-bundle を参照してください。