Skip to main content

Best Practices

PRODUCTIONsdk_best_practicesv3.2.0STABLE

Best Practices

Building a production-grade integration means thinking about more than just successful API calls. You need to handle distributed state, optimize for network latency, and ensure your system is observable when things go wrong.

This guide covers the patterns we've seen work best for scaling documentation pipelines — from ensuring "exactly-once" delivery with idempotency keys to avoiding the "lost update" problem in concurrent environments.

Select a pattern from the sidebar on the right to see idiomatic implementation details. These snippets are designed to be copied directly into your production middleware.

Performance & Efficiency

Minimize latency and stay well within your rate limit quotas by reducing the amount of data transferred.

PracticeBenefitRecommendation
Selective RetrievalLow LatencyUse the ?fields parameter to exclude large content blocks you don't need.
ETag CachingStay in QuotaPass If-None-Match headers to skip downloading data that hasn't changed.
Bulk WritesThroughputBatch up to 50 operations in one call to reduce TCP handshake overhead.
Connection PoolingEfficiencyInitialize the client once and reuse it across your application lifecycle.

Reliability & Correctness

Ensure your data remains consistent even during network partitions or concurrent actor spikes.

PracticeBenefitRecommendation
Idempotency KeysSafe RetriesAssign UUIDs to writes to prevent duplicates when retrying network timeouts.
Optimistic ConcurrencyData IntegrityUse lastSeenVersion to ensure you don't overwrite mid-air changes.
Exponential BackoffStabilityDefault SDK retries doubling wait times to let the API recover from spikes.
Circuit BreakerFault ToleranceFail fast when a dependency is down to prevent resource exhaustion.

Observability Checklist

Never guess why a request failed. Follow these steps to make your integration self-documenting.

#FocusWhat to do
1X-Request-IdEvery response carries this header. Log it! Support cannot help you without a Request ID.
2Structured LogsConnect the SDK to your logger to trace article IDs across system boundaries.
3Audit LogsEvery write via SDK is recorded in the Workspace Audit Log with the API Key name.
4Sandbox ModeTest your logic against the sandbox environment first. It is free and isolated.

Where to go next

Was this section helpful?

Pattern — Safe Retries

import { randomUUID } from ;

"color: ">#8b949e">// Generate a key once for this logical operation.
"color: ">#8b949e">// Persist it if you need to retry across process restarts.
const idempotencyKey = randomUUID();

try {
  const article = await client.articles.create({
    title: ,
    content: ,
  }, { idempotencyKey });
  
  return article;
} catch (err) {
  if (err.retryable) {
    "color: ">#8b949e">// Retrying with the same key is safe. 
    "color: ">#8b949e">// The API will return the original success response 
    "color: ">#8b949e">// if the first call actually succeeded.
    return retryCreate(payload, idempotencyKey);
  }
  throw err;
}

Pro tip

Caching doesn't just save money; it prevents thundering herd problems in your own infrastructure. If multiple nodes start at once, local ETags ensure they don't all pull the same 5MB payload from TechWriter simultaneously.