Search
K
< Back

Integration Optimization

Health Gorilla APIs are designed to support large-scale integrations, including batch record retrievals, population-wide alerting, and document exports. To maintain stable performance, integrations must balance system load, reduce unnecessary overhead, and gracefully handle retries and rate limits.

Design Efficient Queries

Well-scoped queries reduce payload size and server processing time. Aim to retrieve only what you need:

  • Filter by indexed parameters such as patient, date, _lastUpdated, code, or category.
  • Use _elements to limit the fields returned in each resource.
  • Defer large Binary downloads until explicitly needed.
  • Enable gzip compression by including Accept-Encoding: gzip in your request headers.

Example:

GET /fhir/R4/Observation?patient=12345&code=2093-3&date=ge2023-01-01

This request returns only cholesterol results from 2023 onward.

Distribute Workload Predictably

  • Avoid traffic spikes by spreading API calls and job execution across time:
  • Use job queues or schedulers to pace background tasks.
  • Break large retrieval jobs into smaller batches.
  • Use asynchronous operations like Patient360 or $export-ccda for non-user-facing workflows.

To improve connection performance:

  • Reuse HTTPS connections with HTTP/2 and keep-alive.
  • Monitor connection reuse and detect early closure issues.

Stay Within Rate Limits

API rate limits are applied per tenant and endpoint. When exceeded, requests are rejected with 429 errors.

  • Read X-RateLimit-Limit and X-RateLimit-Remaining headers to monitor quota usage.
  • Use pacing strategies to spread requests across time.
  • Apply exponential backoff and jitter to space out retries.

Handle Retries Safely

Unmanaged retries can overwhelm the system or lead to duplicated data.

  • Use the HG-Idempotency-Key header with all POST requests to ensure retry safety.
  • Track and log retry attempts to identify patterns or excessive volumes.
  • Implement circuit breakers to pause retries during sustained failures.
  • Monitor webhook retry behavior to prevent feedback loops or message storms.

Apply Batching Thoughtfully

Batching improves performance by reducing the number of roundtrips, but must be managed carefully.

  • Use FHIR batch endpoints to group related operations.
  • Tune batch size to avoid timeouts or memory issues.
  • Schedule batch jobs during off-peak windows to avoid contention.

Summary of Best Practices

TopicRecommendation
Query EfficiencyFilter by indexed fields and reduce payloads using _elements.
Load DistributionUse queues and schedules to stagger job execution.
Connection ManagementReuse HTTPS connections and enable gzip compression.
Retry BehaviorApply idempotency keys and monitor retry logic.
Rate LimitingRespect usage limits and apply pacing with backoff and jitter.
BatchingUse supported batch operations and time them to avoid peak load.

By following these strategies, you can optimize your integration for high performance, resilience, and scalability.