AppFolio SDK パターン
概要
AppFolio プロパティ管理 REST API のためのプロダクション対応パターン。AppFolio は HTTP Basic 認証とクライアント認証情報を使用し、プロパティ、テナント、リース、作業指示書に対して JSON レスポンスを返します。構造化されたシングルトンクライアントは、認証情報の重複を防ぎ、一貫性のあるエラー処理を強制し、すべてのプロパティ管理エンドポイントにわたってページネーションロジックを集中管理します。
前提条件
- プロバイダーによって確認されたベース URL、認証方法、エンドポイントスコープ、およびターゲットポートフォリオのための管理されたシークレット注入パス。
- すべての変更可能なサービスメソッドに対するスキーマ検証、リクエストタイムアウト、エンドポイント固有のレート制限、および冪等性キー。
- 単体テスト用の合成フィクスチャ。本番のテナント、リース、および支払いペイロードが、デフォルトのモック、ログ、またはエラーメッセージの内容になってはなりません。
手順
- ランタイムごとに1つの契約にバインドされたクライアントを構築し、リクエストを開始する前に欠落または無効な設定を拒否します。
- サービス境界でクエリの範囲とレスポンスの形状を検証し、最小化された型付きフィールドのみを呼び出し元に渡します。
- 分類された
429または不明な書き込みエラーを呼び出し元に返します。呼び出し元がカーソル/キーと遅延を記録した後にのみ、冪等な操作を再試行します。 - 書き込みワークフローを、汎用的な SDK 便利メソッドに埋め込むのではなく、明示的な認可、監査、および調整制御の背後に保ちます。
シングルトンクライアント
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;
}
エラーラッパー
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', `Retry after ${retryAfter ?? 'provider-directed delay'}; do not replay an unknown write automatically`);
}
if (status === 401) throw new AppFolioError(401, 'AUTH', 'Invalid APPFOLIO_CLIENT_ID or SECRET');
throw new AppFolioError(status, 'API_ERROR', `${operation} failed [${status}]: ${err.message}`);
}
}
リクエストビルダー
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; }
}
// 使用法: new AppFolioQuery().status('active').perPage(50).build();
レスポンス型
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';
}
テストユーティリティ
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 };
}
エラーハンドリング
| パターン | 使用タイミング | 例 |
|---|---|---|
safeCall ラッパー | すべての API 呼び出し | 未キャッチの 4xx/5xx がフローをクラッシュさせるのを防ぎます |
| 呼び出し元による 429 の再試行 | レート制限された冪等なバッチ読み取り | カーソル/キーを保持し、Retry-After を尊重した後、意図的に再試行します |
| クライアント初期化時の認証検証 | クライアント初期化 | 認証情報が欠落している場合に早期にスローします |
| ページネーションループ | プロパティ/テナントの一覧表示 | 空のレスポンスになるまで page をインクリメントします |
出力
- 集中化されたタイムアウトとエラー分類動作を備えた、検証済みで契約にバインドされた 1 つの API クライアント
- サービス呼び出し元のための、範囲指定されたクエリパラメータと最小化された型付きレスポンス
- 呼び出し元が所有するカーソル/冪等性/調整の決定を必要とする、明示的なレート制限と不明な書き込み結果
例
プロパティリストの読み取りでは、上限のあるページサイズでクエリを構築し、safeCall を通じて実行し、返されたプロパティ ID と数を合成フィクスチャと照合します。変更操作では、ディスパッチ前に冪等性キーを保持し、タイムアウトまたは 429 を関数の再呼び出しではなく、一時停止/調整条件として扱います。クライアント設定、レスポンススキーマ、または書き込み結果が未確認の場合は、ワークフローを停止し、編集されたエラーを所有者に通知します。
リソース
次のステップ
appfolio-core-workflow-a でパターンを適用します。