Patrones del SDK de AppFolio
Descripción general
Patrones listos para producción para la API REST de administración de propiedades de AppFolio. AppFolio utiliza autenticación básica HTTP con credenciales de cliente y devuelve respuestas JSON para propiedades, inquilinos, contratos de arrendamiento y órdenes de trabajo. Un cliente singleton estructurado evita la dispersión de credenciales, impone un manejo de errores consistente y centraliza la lógica de paginación en todos los endpoints de administración de propiedades.
Requisitos previos
- Una URL base verificada por el proveedor, método de autenticación, alcance del endpoint y ruta de inyección de secreto administrado para el portafolio objetivo.
- Validación de esquema, tiempos de espera de solicitud, límites de tasa específicos del endpoint y claves de idempotencia para todos los métodos de servicio con capacidad de mutación.
- Datos sintéticos para pruebas unitarias; las cargas útiles de producción de inquilinos, contratos y pagos no deben convertirse en contenido predeterminado de simulaciones, registros o mensajes de error.
Instrucciones
- Construir un cliente vinculado al contrato por tiempo de ejecución y rechazar configuraciones faltantes o inválidas antes de que comiencen las solicitudes.
- Validar los límites de consulta y las formas de respuesta en el límite del servicio, luego pasar solo campos tipificados minimizados a los llamadores.
- Devolver un
429clasificado o un fallo de escritura desconocida al llamador; reintentar solo operaciones idempotentes después de que el llamador registre el cursor/clave y la demora. - Mantener los flujos de escritura detrás de controles explícitos de autorización, auditoría y conciliación, en lugar de incrustarlos en ayudantes genéricos del SDK.
Cliente Singleton
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;
}
Envoltorio de Errores
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', `Reintentar después de ${retryAfter ?? 'demora dirigida por el proveedor'}; no reproducir una escritura desconocida automáticamente`);
}
if (status === 401) throw new AppFolioError(401, 'AUTH', 'APPFOLIO_CLIENT_ID o SECRET inválidos');
throw new AppFolioError(status, 'API_ERROR', `${operation} falló [${status}]: ${err.message}`);
}
}
Constructor de Solicitudes
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; }
}
// Uso: new AppFolioQuery().status('active').perPage(50).build();
Tipos de Respuesta
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';
}
Utilidades de Prueba
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 };
}
Manejo de Errores
| Patrón | Cuándo Usarlo | Ejemplo |
|---|---|---|
Envoltorio safeCall | Todas las llamadas a la API | Evita que excepciones 4xx/5xx no capturadas interrumpan los flujos |
| Reintento propiedad del llamador en 429 | Lecturas por lotes idempotentes con límite de tasa | Conservar cursor/clave, respetar Retry-After, luego reintentar deliberadamente |
| Validación de autenticación | Inicialización del cliente | Lanza una excepción temprana si faltan credenciales |
| Bucle de paginación | Listado de propiedades/inquilinos | Incrementar page hasta que la respuesta esté vacía |
Salida
- Un cliente API validado y vinculado al contrato con tiempo de espera centralizado y comportamiento de clasificación de errores
- Parámetros de consulta acotados y respuestas tipificadas minimizadas para los llamadores del servicio
- Resultados explícitos de límite de tasa y escritura desconocida que requieren decisiones de cursor/idempotencia/conciliación propiedad del llamador
Ejemplos
Para una lectura de lista de propiedades, construya una consulta con un tamaño de página limitado, ejecútela a través de safeCall, y verifique los IDs de propiedad devueltos y el recuento contra un dato sintético. Para una mutación, persista una clave de idempotencia antes del envío y trate un tiempo de espera o un 429 como una condición de pausa/conciliación en lugar de llamar a la función nuevamente. Si la configuración del cliente, el esquema de respuesta o el resultado de la escritura no están verificados, detenga el flujo de trabajo y muestre un error editado al propietario.
Recursos
Próximos Pasos
Aplicar patrones en appfolio-core-workflow-a.