SKILL.md
Integration Patterns
Core Concepts
1. API Design for Financial Systems
Financial APIs serve position data, transaction history, account information, reference data, and order submission. Design conventions differ from general-purpose APIs due to the sensitivity, auditability, and volume of financial data.
REST conventions: Resource-oriented design with nouns for financial entities -- /accounts/{id}/positions, /transactions, /orders/{id}/executions. Use HTTP methods semantically: GET for reads (positions, balances), POST for actions (order submission, transfer initiation), PUT/PATCH for updates (account preferences, model assignments). Return standard HTTP status codes with domain-specific error bodies including error codes, human-readable messages, and correlation IDs for traceability. Financial APIs must distinguish between synchronous operations (position lookup returns immediately) and asynchronous operations (transfer initiation returns a 202 Accepted with a status polling URL or webhook callback). Long-running operations such as bulk rebalancing or batch trade submission should use the async pattern to avoid client-side timeouts.
WebSocket and streaming: For real-time use cases (position updates, order status, market data), WebSocket connections provide server-push capability without polling overhead. Financial WebSocket APIs require heartbeat/ping-pong to detect stale connections, automatic reconnection with state recovery (the client must receive missed updates on reconnect), and back-pressure handling when the consumer cannot keep pace with the producer.
Versioning: URL-based versioning (/v2/positions) is the dominant pattern in financial APIs due to its visibility and cacheability. Breaking changes (field removal, type change, semantic change) require a new version; additive changes (new optional fields) do not. Maintain at least two concurrent versions with a published deprecation timeline (typically 12-18 months in financial services).
Pagination for large datasets: Position and transaction endpoints routinely return thousands of records. Cursor-based pagination (opaque next-page token) is preferred over offset-based for consistency during concurrent writes. Include total count estimates, page size limits, and sorting parameters. For bulk data extraction, offer a separate export/download endpoint returning files rather than paginated API calls.
Rate limiting and throttling: Protect systems from burst traffic during market events (open, close, volatility spikes). Use token bucket or sliding window algorithms. Return 429 Too Many Requests with Retry-After headers. Distinguish rate limits per client, per endpoint, and per operation type (reads vs writes).
Authentication and authorization: OAuth 2.0 client credentials flow for service-to-service. API keys with HMAC request signing for simpler integrations. Mutual TLS (mTLS) for high-security custodian and clearing connections. Role-based access control scoped to accounts, operations (read-only vs read-write), and data sensitivity levels. Token expiration and rotation policies must be automated -- expired credentials are a leading cause of integration outages.