CONNECTOR SDK REFERENCE9 of 10
Connector Best Practices
Follow these proven practices to build secure, reliable and high-quality connectors that scale in production.
All PracticesSecurityData & MappingReliabilityPerformanceOperationsTestingDeployment
Build production-grade connectors
Secure by designReliable & resilientHigh quality dataObservable & operableCompliant & auditable
Security & Access
Use least-privilege scopes and roles
Store secrets in a secure vault
Rotate credentials regularly
Use TLS 1.2+ for all connections
Validate certificates
See guide →
Data Protection
Minimize PHI/PII in payloads and logs
Mask or tokenize sensitive data
Encrypt data at rest and in transit
Follow GDPR and local regulations
Honor consent and data rights
See guide →
Idempotency
Use idempotency keys for write operations
Detect and ignore duplicate events
Design idempotent handlers
Store deduplication keys with TTL
Return same result for retries
See guide →
Resilience & Retries
Classify errors as retryable / not retryable
Use exponential backoff with jitter
Respect Retry-After headers
Set appropriate timeouts
Fail fast and recover automatically
See guide →
Rate Limiting
Respect provider rate limits
Implement client-side throttling
Use bulk/batch APIs when available
Cache reference and metadata
Monitor 429 responses
See guide →
Data Mapping
Keep mappings versioned and documented
Preserve original codes and values
Provide traceability of transformations
Handle partial and unknown data
Avoid lossy conversions
See guide →
FHIR & Terminology
Use correct FHIR resource types
Validate with FHIR profiles
Use standard terminologies
Prefer code systems over free text
Check validity and deprecations
See guide →
Observability
Emit metrics for key operations
Log with correlationId and context
Trace external calls end-to-end
Alert on errors, latency and lag
Dashboards for sync and health
See guide →
Performance
Use pagination and cursors
Stream large datasets
Use compression (gzip)
Tune concurrency and batching
Avoid N+1 and chatty calls
See guide →
Versioning & Compatibility
Declare connector and capability versions
Follow semantic versioning
Maintain backward compatibility
Communicate breaking changes
Support graceful upgrades
See guide →
Testing
Unit test handlers and mappers
Use contract tests for external APIs
Test error scenarios and retries
Load test batch operations
Validate with real data samples
See guide →
Deployment & Operations
Use feature flags for rollout
Deploy with blue/green or canary
Monitor after deployment
Prepare rollback plan
Document runbooks and procedures
See guide →
Production readiness checklist
Security review completed
Idempotency implemented
Error handling & retries configured
Observability & alerts in place
Rate limits respected
Data mapping validated
FHIR validation enabled
Load & integration tests passed
Runbooks and rollback plan ready
Recommended defaults
typescriptCopy
{ timeoutMs: 30000, connectTimeoutMs: 10000, maxRetries: 5, retryBackoff: { strategy: 'exponential', initialDelayMs: 1000, maxDelayMs: 60000, jitter: true }, pageSize: 500, maxConcurrency: 5, compression: true, idempotencyTTLMinutes: 1440 }Common pitfalls
Ignoring idempotency leading to duplicates
Logging PHI/PII or secrets
Retrying non-retryable errors
Not handling partial failures
Hardcoding credentials
Ignoring rate limits
Mapping without traceability
No monitoring or alerts
Deploying without rollback plan