Forem: Jakkie Koekemoer

Zero-Downtime Domain Migration: A Developer's Automation Playbook for DNS, Email, and Rollback

Jakkie Koekemoer — Fri, 17 Apr 2026 11:45:48 +0000

Domain migrations fail at the seams between steps. The DNS records move fine, then someone flips the MX records before SPF propagates to the new zone. Or the registrar transfer fires while the old nameservers are still authoritative. The blast radius cloud include a DMARC failure on transactional email, a broken Let's Encrypt DNS-01 challenge, or a two-day authentication outage for OAuth redirects tied to a TXT verification record that got dropped mid-migration.

The failure mode is consistent across these cases: DNS, email, and registrar changes executed as a single coupled batch, with no phase gates and no scripted reversion path. Engineers run through a checklist, something fails mid-flight, and the rollback gets improvised under pressure.

This guide structures the migration as three sequential phases, each with a health check that must pass before the next begins. Every rollback artifact gets produced before the change it protects. The code examples run against the name.com API, which covers all three phases through a single OpenAPI-spec'd surface: DNS CRUD via /core/v1/domains/{domainName}/records, email forwarding via /core/v1/domains/{domainName}/email/forwarding, and transfer operations including unlock, auth code retrieval, and domain-transfer-status-change webhooks.

Before touching anything live, map your blast radius per record type so health checks cover the right surface area:

Layer	Records	What breaks if dropped
Traffic	A, AAAA, CNAME	HTTP/HTTPS endpoints, CDN origins
TLS	CAA, DNS-01 TXT	Certificate issuance and renewal
Email delivery	MX, TXT (SPF, DKIM, DMARC)	Inbound routing, deliverability, DMARC enforcement
Authentication	TXT (Google, AWS, etc.)	OAuth, service integrations, domain verification

Run health check coverage against each row before declaring any phase complete.

Phase 1: Scripted DNS Snapshot, TTL Reduction, and Zone Replication

The snapshot file is the precondition for every rollback decision in this guide. Take it before any other step.

Note: All examples use the name.com sandbox environment. Once you're ready for production, change your API URL to https://api.name.com.

import requests
import json
from datetime import datetime

API_USER = "your_username"
API_TOKEN = "your_api_token"
DOMAIN = "yourdomain.com"

def snapshot_zone(domain):
    url = f"https://api.dev.name.com/core/v1/domains/{domain}/records"
    resp = requests.get(url, auth=(API_USER, API_TOKEN))
    resp.raise_for_status()
    records = resp.json()
    filename = f"snapshot_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
    with open(filename, "w") as f:
        json.dump(records, f, indent=2)
    print(f"Snapshot saved: {filename}")
    return records, filename

records, snapshot_file = snapshot_zone(DOMAIN)

Validate the snapshot before proceeding. A missing CAA record or absent DMARC TXT in the export means you're working from an incomplete source of truth.

REQUIRED_TYPES = {"A", "MX", "TXT", "CAA", "CNAME"}

def validate_snapshot(records):
    found_types = {r["type"] for r in records.get("records", [])}
    missing = REQUIRED_TYPES - found_types
    if missing:
        raise ValueError(f"Snapshot missing record types: {missing}")
    print("Snapshot validated.")

validate_snapshot(records)

With the snapshot confirmed, reduce TTL values well in advance so resolvers flush their caches before the actual cutover. Lower TTL to 300 seconds at least 24 hours before the migration window. Any resolver that previously cached a longer TTL needs time to expire its entry and pick up the shorter value before you cut over.

Note on minimum TTL limits: 300 seconds is the practical floor enforced by most registrar-managed DNS providers, including name.com. Attempting to set a lower value (such as 60s) may be silently ignored or rejected. Some dedicated DNS providers (e.g. Cloudflare non-Enterprise) support TTLs as low as 60 seconds, but this is not universal. Check your provider's documentation before assuming sub-300s values are accepted.

import time

def reduce_ttl(domain, records, target_ttl, auth):
    for record in records.get("records", []):
        record_id = record["id"]
        url = f"https://api.dev.name.com/core/v1/domains/{domain}/records/{record_id}"
        payload = {
            "host": record.get("host", ""),
            "type": record["type"],
            "answer": record["answer"],
            "ttl": target_ttl
        }
        resp = requests.put(url, json=payload, auth=auth)
        resp.raise_for_status()
    print(f"TTL reduced to {target_ttl}s across {len(records.get('records', []))} records")

# Reduce to 300s (the minimum for most providers including name.com)
reduce_ttl(DOMAIN, records, 300, (API_USER, API_TOKEN))
print("Waiting 24h for TTL propagation...")
time.sleep(86400)

# You are now ready to cut over — changes will propagate within ~5 minutes

Waiting the full 24 hours at 300s is necessary because resolvers that previously cached your records with a longer TTL (e.g. 86400s) won't re-check until that original TTL expires. Only after that window can you be confident all resolvers are working with the 300s value and will pick up your cutover quickly.

Phase 2: Email Continuity, Forwarding Rules, and MX Gating

Forwarding rules go up before MX records change. Any mail hitting the old domain during the transition window routes through to the destination address while the new MX records propagate. Set up forwarding using the name.com API's create-email-forwarding endpoint:

curl -u "username:apitoken" --request POST \
  --url https://api.dev.name.com/core/v1/domains/yourdomain.com/email/forwarding \
  --header 'Content-Type: application/json' \
  --data '
{
  "emailBox": "admin",
  "emailTo": "webmaster@example.com"
}
'

The /email/forwarding endpoint accepts one rule per request, so loop over your mailbox list when automating this across a team.

Before touching MX records, get SPF, DKIM, and DMARC TXT records in place on the destination zone and confirmed as propagated. Google and Yahoo mandated DMARC authentication for bulk senders in February 2024, and the enforcement is active. A migration that drops the DMARC TXT record before the MX cutover completes will route outbound mail to spam or trigger hard rejections, showing up as a deliverability incident in your postmaster dashboard hours after the fact.

Update the auth records using the same update-record endpoint from Phase 1, then run a propagation check before allowing the MX flip:

#!/bin/bash
DOMAIN="yourdomain.com"
MAX_ATTEMPTS=30
INTERVAL=15

for i in $(seq 1 $MAX_ATTEMPTS); do
    RESULT=$(dig TXT _dmarc.$DOMAIN +short | tr -d '"')
    echo "[$(date +%H:%M:%S)] Attempt $i: $RESULT"
    if [[ "$RESULT" == *"v=DMARC1"* ]]; then
        echo "DMARC record confirmed. Proceeding to MX flip."
        exit 0
    fi
    sleep $INTERVAL
done

echo "DMARC propagation timed out after $((MAX_ATTEMPTS * INTERVAL))s. Halting migration."
exit 1

A code 1 exit means you halt everything. The same polling pattern applies to SPF and DKIM: run a dig TXT check for each record before advancing. The MX flip goes through the update-record endpoint. Patch the existing MX record IDs using PUT /core/v1/domains/{domainName}/records/{id}, and leave the forwarding rules active for at least 48 hours post-cutover to catch any in-flight messages.

Phase 3: Programmatic Registrar Transfer, Webhooks, and Lock Sequencing

The registrar transfer carries the longest irreversibility window, which makes sequencing critical. The correct order:

Unlock the domain
Retrieve the auth code
Initiate the transfer at the receiving registrar
Subscribe to the domain-transfer-status-change webhook

import requests

def unlock_domain(domain, auth):
    url = f"https://api.dev.name.com/core/v1/domains/{domain}"
    resp = requests.patch(url, json={"locked": False}, auth=auth)
    resp.raise_for_status()
    print(f"Domain {domain} unlocked.")

def get_auth_code(domain, auth):
    url = f"https://api.dev.name.com/core/v1/domains/{domain}/authCode"
    resp = requests.get(url, auth=auth)
    resp.raise_for_status()
    return resp.json().get("authCode")

unlock_domain(DOMAIN, (API_USER, API_TOKEN))
auth_code = get_auth_code(DOMAIN, (API_USER, API_TOKEN))
print(f"Auth code retrieved: {auth_code}")

Once you've initiated the transfer at the receiving registrar with the auth code, subscribe to the webhook so your system receives async status updates:

def subscribe_transfer_webhook(domain, callback_url, auth):
    url = "https://api.dev.name.com/core/v1/notifications"
    payload = {
        "event": "domain-transfer-status-change",
        "domainName": domain,
        "url": callback_url
    }
    resp = requests.post(url, json=payload, auth=auth)
    resp.raise_for_status()
    print(f"Webhook subscribed: {resp.json()}")

subscribe_transfer_webhook(
    DOMAIN,
    "https://your-server.com/webhooks/transfer",
    (API_USER, API_TOKEN)
)

The webhook delivers a payload with a status field. Wire up a Flask endpoint to handle it:

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks/transfer", methods=["POST"])
def transfer_webhook():
    payload = request.get_json()
    status = payload.get("status")
    domain = payload.get("domainName")

    if status in ("failed", "cancelled"):
        print(f"Transfer {status} for {domain}. Triggering rollback.")
        relock_domain(domain)
    elif status == "completed":
        print(f"Transfer completed for {domain}. Running post-transfer validation.")
        run_post_transfer_checks(domain)

    return jsonify({"received": True}), 200

If transfer initiation fails or the webhook fires a failure event, call POST /core/v1/domains/{domainName}/actions/lock immediately. An unlocked domain sitting in limbo is an active attack surface.

def relock_domain(domain, auth=(API_USER, API_TOKEN)):
    url = f"https://api.dev.name.com/core/v1/domains/{domain}/actions/lock"
    resp = requests.post(url, auth=auth)
    resp.raise_for_status()
    print(f"Domain {domain} re-locked.")

GoDaddy's API surfaces transfer status through polling only, which means a rollback trigger fires minutes after a failure event on an exposed domain. Namecheap's transfer API requires polling as well, with no webhook event support. The name.com domain-transfer-status-change webhook fires immediately on status change, giving the auto-relock function enough headroom to run in under a second of the failure event. That speed matters when the domain is unlocked.

Have a Clear Rollback Plan: Snapshot Design and Reversion Procedures

The rollback snapshot JSON from Phase 1 needs to contain everything required for a clean manual reversion. The minimum viable structure:

{
  "captured_at": "2024-11-15T09:30:00Z",
  "domain": "yourdomain.com",
  "nameservers": ["ns1.name.com", "ns2.name.com"],
  "records": [
    {
      "id": "12345",
      "host": "",
      "type": "A",
      "answer": "203.0.113.10",
      "ttl": 300
    },
    {
      "id": "12346",
      "host": "",
      "type": "MX",
      "answer": "mail.yourdomain.com",
      "ttl": 300
    }
  ],
  "forwarding_rules": [
    {
      "emailBox": "admin",
      "emailTo": "admin@oldprovider.com"
    }
  ]
}

Rollback scope by layer:

DNS-level: Re-create divergent records from the snapshot using POST /core/v1/domains/{domainName}/records. Compare the live zone against the snapshot by diffing jq-extracted record sets from both sources.
Email-level: Delete forwarding rules added during the migration via DELETE /core/v1/domains/{domainName}/email/forwarding/{emailBox}, then restore original MX records from the snapshot using the record IDs stored in the JSON.
Transfer-level: Re-lock the domain via PATCH /core/v1/domains/{domain}

Rollback triggers are human-evaluated conditions that require a deliberate go/no-go decision before execution. Automate the detection, but keep a person in the approval loop. Conditions that warrant investigation and a reversion decision:

HTTPS endpoints returning 5xx errors for more than 10 minutes post-cutover
dig MX yourdomain.com returning empty or unexpected results 30 minutes after the flip
DMARC reports showing authentication failure rates spiking above baseline
DNS propagation incomplete after 90% of the expected window (typically 24h at 300s TTL)

Set a hard decision deadline: 2 hours post-cutover for DNS changes, 24 hours for the MX flip. After TTLs have propagated across the global resolver population, the cost of rolling back climbs substantially. Make the call while reversion is still cheap.

The rollback runbook, executed manually and verified at each step:

Pull the snapshot: cat snapshot_20241115_093000.json | jq '.records'
Diff against live: curl -s -u "user:token" "https://api.dev.name.com/core/v1/domains/yourdomain.com/records" | jq '.records' > live.json && diff snapshot_records.json live.json
Re-create any missing or divergent records via POST /core/v1/domains/{domainName}/records
Restore MX records to original values using the record IDs from the snapshot
Re-lock the domain if transfer was initiated
Run the propagation polling script to confirm resolution returns to pre-migration values
Verify forwarding rules via GET /core/v1/domains/{domainName}/email/forwarding/{emailBox}

Execute each step individually, verify its output, and only proceed when the previous step's verification passes. This approach draws directly on the blue-green deployment and automated rollback principles used in zero-downtime database migrations: staged state transitions with explicit validation gates between them.

Observability: Propagation Polling, Divergence Alerts, and CI/CD Integration

Poll two resolvers in parallel and log every result with a timestamp. Divergence between 8.8.8.8 and 1.1.1.1 during propagation is expected. Both converging to the correct value is your success condition.

#!/bin/bash
DOMAIN="yourdomain.com"
EXPECTED_IP="203.0.113.10"
MAX_ITERATIONS=48
INTERVAL=300  # 5 minutes
LOGFILE="propagation_$(date +%Y%m%d_%H%M%S).log"

for i in $(seq 1 $MAX_ITERATIONS); do
    TS=$(date +%H:%M:%S)
    GOOGLE=$(dig @8.8.8.8 A $DOMAIN +short)
    CF=$(dig @1.1.1.1 A $DOMAIN +short)
    echo "[$TS] Google: $GOOGLE | Cloudflare: $CF" | tee -a $LOGFILE

    if [[ "$GOOGLE" == "$EXPECTED_IP" && "$CF" == "$EXPECTED_IP" ]]; then
        echo "Propagation confirmed on both resolvers." | tee -a $LOGFILE
        exit 0
    fi
    sleep $INTERVAL
done

echo "Propagation check failed after $((MAX_ITERATIONS * INTERVAL / 3600))h." | tee -a $LOGFILE
exit 1

The log file this produces is your audit trail: timestamped evidence of when each record resolved to the new value. The EU NIS2 Directive, which took effect in October 2024, places DNS providers and registrars under incident reporting and change management obligations. An automatically timestamped log of every DNS state transition covers the audit trail requirement without additional tooling.

Structure the full migration as a GitHub Actions workflow where each phase is a separate job with needs: dependencies. Failed jobs halt the pipeline and surface the rollback job.

name: Domain Migration

on:
  workflow_dispatch:

jobs:
  snapshot:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Take zone snapshot
        run: python scripts/snapshot_zone.py
        env:
          NAME_COM_USER: ${{ secrets.NAME_COM_USER }}
          NAME_COM_TOKEN: ${{ secrets.NAME_COM_TOKEN }}
      - name: Validate snapshot
        run: python scripts/validate_snapshot.py
      - uses: actions/upload-artifact@v4
        with:
          name: zone-snapshot
          path: snapshot_*.json

  ttl_ramp:
    needs: snapshot
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          name: zone-snapshot
      - name: Reduce TTL to 300s
        run: python scripts/reduce_ttl.py --ttl 300
      - name: Wait 24h
        run: sleep 86400
      - name: Reduce TTL to 60s
        run: python scripts/reduce_ttl.py --ttl 60

  email_gate:
    needs: ttl_ramp
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set forwarding rules
        run: bash scripts/set_forwarding.sh
      - name: Check DMARC propagation
        run: bash scripts/check_dmarc.sh

  mx_flip:
    needs: email_gate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Update MX records
        run: python scripts/flip_mx.py
      - name: Verify MX resolution
        run: bash scripts/verify_mx.sh

  transfer_init:
    needs: mx_flip
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Unlock domain and get auth code
        run: python scripts/unlock_and_auth.py
      - name: Subscribe transfer webhook
        run: python scripts/subscribe_webhook.py

  rollback:
    if: failure()
    needs: [snapshot, ttl_ramp, email_gate, mx_flip, transfer_init]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          name: zone-snapshot
      - name: Execute rollback
        run: python scripts/rollback.py

The needs: chain enforces the phase gate requirement without custom orchestration logic. The if: failure() condition on the rollback job means it runs only when something upstream fails, and the snapshot artifact from the first job is available to it via download-artifact.

Route 53 offers solid DNS scripting via Boto3, but it covers only the DNS layer, requires full AWS ecosystem buy-in, and provides no native email forwarding API. Cloudflare's DNS API is excellent but operates as a DNS host and proxy, covering only Phase 1 of this pipeline. The name.com API covers the DNS zone, email forwarding, and registrar transfer operations through a single authenticated surface, which is why the code examples above are all against it. Vercel, Replit, and Netlify run their domain operations on the same infrastructure.

Before You Touch Anything: Run the Zone Snapshot Right Now

If you're planning a migration and haven't taken a snapshot yet, do it now. You need a name.com API token first. Generate one in the API settings section of your name.com account, then pull your current zone state to a timestamped file:

curl -s -u "username:token" \
  "https://api.dev.name.com/core/v1/domains/yourdomain.com/records" \
  | jq '.' > snapshot_$(date +%Y%m%d_%H%M%S).json

Confirm the output JSON contains your A, MX, and TXT records before proceeding. That file is the precondition for the TTL ramp, the rollback diff, and the post-transfer validation. A migration without a verified pre-migration snapshot has no clean reversion path. Commit it to your repo and treat it as an immutable artifact for the duration of the operation.

Get started with the name.com API to grab your API key and pull your current DNS records in under five minutes.

Have you run a domain migration that went sideways despite a solid checklist? Drop your experience in the comments, including where the seam broke and what you did to recover.

Document Workflow Automation: An Architectural Guide to Building API-Driven Document Pipelines

Jakkie Koekemoer — Fri, 03 Apr 2026 16:24:45 +0000

A PDF generation script that breaks on special characters. A cron job that retries failed document conversions by rerunning the entire job. An eSign flow tracked in a shared spreadsheet where "sent" means someone sent an email. These are the actual engineering artifacts that accumulate when document workflows grow faster than the architecture beneath them.

The scale problem compounds fast. A team processing 200 contracts a month can survive on scripts and email hand-offs. At 2,000 contracts, those same workflows are the bottleneck. At 20,000, engineers are maintaining hacks that should have been replaced two years ago: retry logic bolted onto cron jobs, signing flows with no audit trail, and PDF generation that silently drops content when a CRM field contains a Unicode character.

The global intelligent document processing market was valued at \$2.3B in 2024 and is projected to reach \$12.35B by 2030 at a 33.1% CAGR, not because AI is newly fashionable, but because manual document handling is a measurable operational ceiling. The organizations crossing that ceiling are adopting an architectural model, not just swapping individual tools.

Most teams are missing a framework for assembling generation, conversion, and signing operations into a pipeline that's resilient, auditable, and testable. This guide provides that framework, then grounds it in working Python examples against a real REST API suite.

Anatomy of a Document Automation Pipeline: The Five Stages

Every document workflow automation pipeline, regardless of domain, decomposes into five discrete stages. Get clear on this model before you write a single API call.

Stage 1 is intake. You receive or capture the source data that will drive the document. This might be a webhook payload from your CRM when a deal closes, a form submission, or a batch export from an ERP system. Without schema validation, deduplication, and an observable queue, documents arrive out of order, get processed twice, or disappear without trace.

Stage 2 is generation. You render a document from a template and the structured data from stage 1. Common outputs include contracts, invoices, compliance reports, and onboarding kits. The failure modes here are template version drift (production runs a different template version than staging), no validation of input data against the template's expected schema, and no idempotent retry path if the generation call fails partway through.

Stage 3 is processing. You transform, extract from, or optimize the generated document. This covers format conversion (DOCX to PDF), content extraction for downstream indexing, compression, and linearization for fast web delivery. When processing steps chain with no error isolation, a failed compression step blocks the entire document from reaching signing.

Stage 4 is signing. You route the document for signature, track signer status, and capture consent with a full audit trail. Manual polling for signer status, no webhook-driven callbacks, and no programmatic access to the audit log are the common failure modes you'll encounter when a compliance review is triggered.

Stage 5 is archival and distribution. You store the signed document with a retention policy and push it to downstream systems: your DMS, CRM, or data warehouse. The failure modes are no content-addressed versioning, no record of which document version was signed, and no delivery confirmation to downstream consumers.

Idempotency is a first-class requirement at every stage. Each operation should be safely retryable, meaning the same inputs produce the same output and a retried call doesn't create a duplicate document, signing request, or archive record. You implement idempotency in your orchestration layer by generating a unique key per document job and checking it before re-processing. The API doesn't handle this for you automatically.

A well-designed document automation pipeline flows through these stages in sequence:

One constraint worth knowing upfront: the three APIs in this stack don't share a document ID namespace, and each stage boundary requires a file handoff. DocGen returns the rendered document as base64 in the response body. You decode it and either save it to disk or upload it directly to PDF Services. PDF Services returns a resultDocumentId that you download as a file, then re-upload to eSign, which runs on a different host with different authentication. This handoff pattern makes each stage independently testable and replayable.

Architectural Decision Framework: Four Axes Before You Write Code

Four decisions determine whether your document pipeline scales cleanly or becomes the thing your team rewrites in 18 months.

Axis 1: REST API vs. SDK

Use REST APIs for cloud-native, horizontally scalable pipelines where document operations are stateless HTTP calls. Use an SDK for on-premise deployments, air-gapped environments, or latency-sensitive processing where network round-trips are a constraint. Foxit offers both: REST APIs for cloud-native pipelines and PDF SDKs for on-premise or air-gapped deployments, so this is a real architectural choice. If your document pipeline runs inside a regulated environment where data can't leave the network perimeter, the SDK is the correct answer regardless of how convenient the REST API is.

Axis 2: Synchronous vs. Asynchronous Processing

This is the most consequential call you'll make, and it varies by stage within a single pipeline.

Factor	Synchronous	Asynchronous
Document size	Under ~10 pages	Large or variable-length
SLA requirement	Sub-second response	Variable completion time acceptable
Typical use case	Real-time contract preview	Batch invoice processing
Error handling	Inline exception handling	Dead-letter queue, retry on callback
Foxit API example	DocGen (returns document in response body)	PDF Services (returns taskId, poll for result); eSign (webhook callback on folder execution)

The Foxit suite illustrates this split directly. DocGen is synchronous: POST your template and data payload, get the rendered document back immediately in the response body, with no taskId and no polling. PDF Services is asynchronous: a conversion call returns a taskId, and you poll a status endpoint until the result is ready. eSign is asynchronous via webhooks: creating a folder returns immediately, and the API delivers a callback to your registered endpoint when all signers complete. Design your pipeline around this reality rather than assuming a uniform execution model across all three APIs.

Axis 3: Linear Pipeline vs. Event-Driven Architecture

A linear pipeline, where stage A blocks until complete before stage B starts, works for simple three-stage flows with predictable volume and acceptable end-to-end latency. An event-driven pipeline, where each stage emits a completion event consumed by the next stage, is the right choice when you need error isolation (a failed stage 3 doesn't block stage 2 outputs from being replayed), partial replay (reprocess from stage 2 without regenerating the document), or parallel processing branches (send the same document to multiple downstream consumers simultaneously).

For pipelines that start as linear but need to scale, n8n is a practical bridge. You can call Foxit's REST APIs from n8n workflows via HTTP Request nodes, which lets you wire pipeline stages without writing custom glue code while you validate the workflow logic before committing to a fully coded implementation.

Axis 4: Error Handling Strategy for Document Pipelines

Three components belong in your initial design, not bolted on afterward.

The first is idempotency keys. Generate a unique key per document job (a UUID tied to the source record ID and timestamp works well) and check it before re-processing. If a worker crashes mid-job and the job re-queues, the idempotency key prevents duplicate processing.

The second is dead-letter handling. Define what happens to a document that has failed three consecutive processing attempts. It should route to a dead-letter queue with the failure reason and enough context to replay it manually or trigger an alert.

The third is a circuit breaker. If PDF Services returns 5xx responses on five consecutive calls within 30 seconds, stop sending requests and return a fast failure to the calling system. This prevents a degraded upstream API from exhausting your worker pool and cascading failures downstream. The circuit breaker pattern maps cleanly onto any stateless HTTP integration.

Building the Pipeline: Foxit APIs in Practice

We'll use Foxit's PDF Services, DocGen, and eSign APIs for the examples below. The patterns translate to any REST-based document API, but these are the endpoints we'll call.

Document Generation with the DocGen API

DocGen takes a DOCX template (encoded as base64) and a JSON data payload, and returns the rendered document immediately in the response body. There's no templateId concept, so you send the template inline with every request. That means you own template versioning. Keep your templates in version control and pin the version used for each job to your event log.

The request uses client_id and client_secret as HTTP headers against na1.fusion.foxit.com.


# Illustrative example - not production code
import base64
import requests
import json

def generate_contract(template_path: str, data: dict) -> bytes:
    with open(template_path, "rb") as f:
        template_b64 = base64.b64encode(f.read()).decode("utf-8")

    payload = {
        "outputFormat": "pdf",
        "documentValues": data,
        "base64FileString": template_b64
    }

    response = requests.post(
        "https://na1.fusion.foxit.com/document-generation/api/GenerateDocumentBase64",
        headers={
            "client_id": "YOUR_CLIENT_ID",
            "client_secret": "YOUR_CLIENT_SECRET",
            "Content-Type": "application/json"
        },
        json=payload
    )
    response.raise_for_status()
    result = response.json()
    return base64.b64decode(result["base64FileString"])

# Data pulled from your CRM or ERP; validate against your template schema before calling
contract_data = {
    "client_name": "Acme Corp",
    "contract_value": "48000",
    "effective_date": "2025-09-01",
    "payment_terms": "Net 30"
}

pdf_bytes = generate_contract("templates/msa_v3.docx", contract_data)

Validate your data payload against the template's expected field schema before the API call. DocGen doesn't catch type errors or missing fields with a clean error response. You get a malformed document instead. A Pydantic model or JSON Schema validation step before the POST saves significant debugging time.

PDF Processing with the PDF Services API

The most common PDF Services operation is conversion, and the DOCX-to-PDF call is also the simplest entry point for teams new to the API. PDF Services uses a two-step pattern: upload the source file first to get a documentId, then call the operation endpoint with that ID. Because operations are asynchronous, the call returns a taskId that you poll until the result is available.


# Illustrative example - not production code
import time
import requests

PDF_SERVICES_HOST = "https://na1.fusion.foxit.com"
HEADERS = {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
}

def upload_document(file_bytes: bytes, filename: str) -> str:
    response = requests.post(
        f"{PDF_SERVICES_HOST}/pdf-services/api/documents/upload",
        headers=HEADERS,
        files={"file": (filename, file_bytes, "application/octet-stream")}
    )
    response.raise_for_status()
    return response.json()["documentId"]

def poll_task(task_id: str) -> str:
    while True:
        status_resp = requests.get(
            f"{PDF_SERVICES_HOST}/pdf-services/api/tasks/{task_id}",
            headers=HEADERS
        )
        status_resp.raise_for_status()
        status_data = status_resp.json()

        if status_data["status"] == "COMPLETED":
            return status_data["resultDocumentId"]
        elif status_data["status"] == "FAILED":
            raise RuntimeError(f"Task failed: {status_data}")
        time.sleep(2)

def download_document(document_id: str) -> bytes:
    response = requests.get(
        f"{PDF_SERVICES_HOST}/pdf-services/api/documents/{document_id}/download",
        headers=HEADERS
    )
    response.raise_for_status()
    return response.content

def convert_docx_to_pdf(docx_bytes: bytes) -> bytes:
    doc_id = upload_document(docx_bytes, "document.docx")
    response = requests.post(
        f"{PDF_SERVICES_HOST}/pdf-services/api/documents/create/pdf-from-word",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"documentId": doc_id}
    )
    response.raise_for_status()
    result_doc_id = poll_task(response.json()["taskId"])
    return download_document(result_doc_id)

def extract_text(pdf_bytes: bytes) -> str:
    doc_id = upload_document(pdf_bytes, "document.pdf")
    response = requests.post(
        f"{PDF_SERVICES_HOST}/pdf-services/api/documents/modify/pdf-extract",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"documentId": doc_id, "extractType": "TEXT"}
    )
    response.raise_for_status()
    result_doc_id = poll_task(response.json()["taskId"])
    return download_document(result_doc_id).decode("utf-8")

The pdf-extract endpoint pulls text from the PDF (pass extractType as TEXT, IMAGE, or PAGE depending on what you need). Both conversion and extraction follow the same upload, execute, poll, download cycle. Feed the text output to a downstream search index so the document is queryable immediately after processing.

Signature Orchestration with the eSign API

The eSign API uses OAuth2 rather than header-based authentication. Your first call exchanges client_id and client_secret for a Bearer token on a separate host (na1.foxitesign.foxit.com).


# Illustrative example - not production code
import json
import requests
from flask import Flask, request as flask_request

ESIGN_HOST = "https://na1.foxitesign.foxit.com"

def get_esign_token(client_id: str, client_secret: str) -> str:
    response = requests.post(
        f"{ESIGN_HOST}/api/oauth2/access_token",
        data={
            "grant_type": "client_credentials",
            "client_id": client_id,
            "client_secret": client_secret
        }
    )
    response.raise_for_status()
    return response.json()["access_token"]

def create_signing_folder(token: str, pdf_bytes: bytes, signers: list) -> str:
    folder_payload = {
        "folderName": "MSA - Acme Corp",
        "parties": [
            {
                "firstName": s["first_name"],
                "lastName": s["last_name"],
                "emailId": s["email"],
                "permission": "FILL_FIELDS_AND_SIGN",
                "sequence": s["sequence"]
            }
            for s in signers
        ]
    }

    response = requests.post(
        f"{ESIGN_HOST}/api/folders/createfolder",
        headers={"Authorization": f"Bearer {token}"},
        files={
            "file": ("contract.pdf", pdf_bytes, "application/pdf"),
            "data": (None, json.dumps(folder_payload), "application/json")
        }
    )
    response.raise_for_status()
    return response.json()["folderId"]

# Webhook handler receives the folder-executed event
app = Flask(__name__)

@app.route("/webhooks/esign", methods=["POST"])
def esign_webhook():
    event = flask_request.json
    if event.get("event_type") == "folder_executed":
        folder_id = event["folder_id"]
        signed_doc_url = event["documents"][0]["download_url"]
        archive_signed_document(folder_id, signed_doc_url)
    return "", 200

Register your webhook endpoint in the eSign developer portal settings. When a folder is executed (all signers complete), the API POSTs the event payload to your endpoint. Extract the signed document URL from the callback and pass it to your archival stage. The eSign API also exposes a folder activity history endpoint that returns a complete audit trail: signer identity, timestamp, IP address, and authentication method for every interaction with the folder.

Chaining the Pipeline Stages with Idempotency

The file handoff between stages is explicit by design. This minimal orchestration wrapper chains all three stages and demonstrates the idempotency pattern:


# Illustrative example - not production code
import uuid

def run_document_pipeline(job_id: str, template_path: str, data: dict, signers: list):
    idempotency_key = f"{job_id}:{uuid.uuid4()}"

    if is_already_processed(idempotency_key):
        return  # Safe to retry

    # Stage 2: Generate (DocGen returns PDF bytes synchronously)
    pdf_bytes = generate_contract(template_path, data)
    log_pipeline_event(job_id, "generated", hash_document(pdf_bytes))

    # Stage 3: Process (extract text for indexing; convert if needed)
    extracted = extract_text(pdf_bytes)
    index_document(job_id, extracted)
    log_pipeline_event(job_id, "processed", hash_document(pdf_bytes))

    # Stage 4: Sign (eSign returns folder ID; completion arrives via webhook)
    token = get_esign_token("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
    folder_id = create_signing_folder(token, pdf_bytes, signers)
    log_pipeline_event(job_id, "sent_for_signature", folder_id)

    mark_processed(idempotency_key)

For async pipelines handling thousands of documents per hour, replace direct function calls with queue messages. Each stage worker pulls a job from Redis or Amazon SQS, executes the API call, ACKs on success, and publishes a completion event to the next stage's queue. If a worker crashes mid-job, the unACKed message re-queues and the idempotency key prevents re-processing a document that's already been completed.

Auditability and Compliance by Design

GDPR, HIPAA, and SOC 2 Type II each impose specific requirements around document lifecycle traceability. Retrofitting an audit layer onto a pipeline that wasn't designed for it takes far more work than building it in from the start.

The event sourcing pattern fits document pipelines directly. Maintain an append-only log of every document event: created, converted, sent_for_signature, signed, archived. Use a stable document_id as the primary key. This log makes replay straightforward: if signing fails, you can replay from the processing output without regenerating the document from scratch. Each event record should include the stage name, timestamp, operator identity, and a SHA-256 hash of the document bytes at that stage.

The SHA-256 hash at each stage is your tamper detection mechanism. If the hash of the document presented for signing doesn't match the hash recorded at generation, you have an integrity problem that's immediately visible. This satisfies document integrity requirements in regulated industries without any additional tooling.

The Foxit eSign API's built-in audit trail captures signer identity, timestamp, IP address, and authentication method for every folder interaction. Query the folder activity history endpoint to retrieve this data and persist it in your own audit store alongside your pipeline event log. Storing it in your own system, rather than relying solely on the eSign provider's records, gives you a complete, portable audit trail that survives a provider migration.

Scaling Document Workflow Automation Without Rebuilding It

Batch Ingestion

Place incoming document jobs on a queue (Redis list or SQS FIFO queue) and run a pool of stateless worker processes. Each worker pulls a job, executes the API call with an idempotency key, and ACKs on success. Dead-letter routing handles permanently failed documents.

This pattern processes thousands of documents per hour without hammering the API or requiring coordination between workers. Because each REST API call is stateless, workers scale horizontally without any shared state. You add capacity by adding workers, not by redesigning the pipeline.

Credit Quota and Backoff

Foxit's pricing model is credit-based: API calls consume credits, and calls pause when credits are exhausted until renewal or upgrade. Implement exponential backoff with jitter on 5xx responses as a general practice for any REST API integration.


# Illustrative example - not production code
import time
import random
import requests

def api_call_with_retry(url, headers, payload, max_retries=4):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=payload)
        if response.status_code < 500:
            return response
        wait = (2 ** attempt) + random.uniform(0, 1)
        time.sleep(wait)
    response.raise_for_status()

Log quota exhaustion as a separate metric category. Consistent credit exhaustion signals that you need to upgrade your plan, and you shouldn't have to dig through application logs to detect it.

Observability

Instrument each pipeline stage with three metrics: processing latency (time from job enqueue to stage completion), error rate per stage, and document volume per time window. Use structured JSON logging so stage failures are queryable without parsing free-text log lines. OpenTelemetry makes it straightforward to emit these metrics in a vendor-neutral format.

A document that enters the pipeline and never exits is a data integrity problem. Track in-flight documents explicitly: when a job enters signing, record it. When the eSign webhook fires, close the record. Any job that's been in stage 4 for longer than your expected SLA without a webhook callback warrants an alert, not just a log entry.

Build Your First Document Pipeline Stage This Week

Moving from a handful of scripts to a production document pipeline is a smaller jump than it looks. You don't need all five stages on day one.

Sign up for a free account at developer-api.foxit.com (no credit card required) to get API credentials in minutes. Then make a single conversion call: POST a DOCX file to the PDF Services endpoint using the Python example above and verify you get a valid PDF back. That one round-trip confirms your authentication, network path, and the core integration pattern before you write any orchestration code.

From there, choose one document type in your system that's still generated or processed by hand and map it against the five-stage model from the second section. Start at the highest-friction stage, not necessarily stage 1. If generation is the bottleneck, test DocGen templates against real data payloads in the Developer Playground before writing integration code. If signing is the pain point, wire up eSign folder creation and a webhook handler to close the loop.

Every pattern in this guide, idempotency keys, event-sourced audit logs, async stage handoffs, and circuit breakers, works with any document API stack. A single REST API suite that covers generation, processing, and signing reduces the number of auth models you manage, shrinks the integration surface, and gives you one consistent debugging path when something breaks across stages. That is what it looks like to treat document workflow automation as a first-class architectural concern instead of a pile of scripts that should have been retired two years ago.

Start building your first pipeline stage today.

Frequently Asked Questions

What is document workflow automation?

Document workflow automation replaces manual, script-driven document operations (generation, conversion, signing, and archival) with a structured API-driven pipeline. Each stage is independently testable, retryable via idempotency keys, and observable through structured event logs. At scale (thousands of documents per hour), automation eliminates the bottlenecks created by cron jobs, shared spreadsheets, and one-off scripts.

When should I use a synchronous vs. asynchronous document API?

Use synchronous APIs when you need sub-second responses for small documents, for example, real-time contract previews under approximately 10 pages. Use asynchronous APIs (polling or webhook-driven) for large or variable-length documents, batch invoice processing, or any workflow where variable completion time is acceptable. Many document API suites, including Foxit's, mix both models across different endpoints, so design each pipeline stage around the actual execution model of the specific API call it makes.

How do I make a document pipeline idempotent?

Generate a unique key per document job (a UUID tied to the source record ID and timestamp works well) and check whether that key has already been processed before executing any stage. Store processed keys in a fast key-value store (Redis is a common choice). On retry, the idempotency check returns early without duplicating the document, signing request, or archive record. This is an orchestration-layer responsibility because the document API itself doesn't provide it automatically.

What compliance requirements apply to document pipelines?

GDPR, HIPAA, and SOC 2 Type II each require document lifecycle traceability. Implement an append-only event log keyed by a stable document_id, capturing stage name, timestamp, operator identity, and a SHA-256 hash of the document at each stage. For eSign specifically, store the provider's audit trail (signer identity, IP address, authentication method, timestamp) in your own system so the record is portable across provider migrations.

If you've built a document pipeline at scale, I'd genuinely like to hear where the architecture broke down. Was it the signing flow, the retry logic, something at the intake stage? Drop a comment below or share what you'd do differently.

The Complete Guide to CNAME Records: Zone Apex Limitations, ANAME Records, and Common Pitfalls

Jakkie Koekemoer — Mon, 30 Mar 2026 15:50:46 +0000

You're setting up your new blog on Heroku. Their docs tell you to add a CNAME pointing to your-app.herokuapp.com. You open your DNS panel, create www.yourdomain.com as a CNAME, and it works perfectly.

Then you try to do the same thing for the root domain, yourdomain.com, and hit an error: "CNAME records cannot be created for the root domain."

This isn't a Heroku problem. It's not a bug in your DNS provider either. It's a rule baked into the DNS specification itself: a CNAME record can't coexist with other record types at the zone apex. Because the root of your domain must carry records like SOA and NS, a standard CNAME simply isn't allowed there.

Modern DNS providers work around this with features called ALIAS, ANAME, or CNAME flattening. Platforms like Heroku also document how to configure root domain pointing using these mechanisms.

That said, the underlying rule still matters. To understand why this restriction exists, and when it causes real production problems, you need to understand how CNAMEs actually work.

How CNAME Records Work

A CNAME (Canonical Name) record creates an alias. It tells DNS: "Don't answer this query directly. Go look up this other hostname instead."

Here's what happens when someone visits blog.example.com and you have a CNAME pointing to app-123.platform.com:

Browser asks DNS: "What's the IP for blog.example.com?"
DNS responds: "I don't have an IP. Look up app-123.platform.com instead."
Browser asks DNS: "What's the IP for app-123.platform.com?"
DNS responds: "That's 203.0.113.45."
Browser connects to 203.0.113.45.

You can see this in action with the dig command on a Linux or MacOS terminal:

dig www.microsoft.com

…
;; ANSWER SECTION:
www.microsoft.com.          2440    IN  CNAME   www.microsoft.com-c-3.edgekey.net.
www.microsoft.com-c-3.edgekey.net.  187 IN  CNAME   www.microsoft.com-c-3.edgekey.net.globalredir.akadns.net.
www.microsoft.com-c-3.edgekey.net.globalredir.akadns.net. 187 IN CNAME e13678.dscb.akamaiedge.net.
e13678.dscb.akamaiedge.net. 13  IN  A   2.22.197.228

The response includes both the full CNAME chain and the final A record. Notice that multiple lookups happened. Every CNAME adds latency because each one requires an additional DNS query. For users on slow connections or far from your nameservers, that adds up.

Why use a CNAME at all, then? Because cloud platforms can (and do) change IPs without warning. When Heroku moves your app to a new server, app-123.herokuapp.com automatically resolves to the new IP. Your CNAME keeps working. An A record would break until you manually updated it.

The tradeoff is speed versus flexibility. CNAMEs give you automatic IP updates at the cost of an extra lookup on every visit. Understanding the difference between these DNS record types helps you make the right call for your infrastructure.

The Zone Apex Problem

If a DNS name has a CNAME record, it must not have any other record types associated with it.

That rule comes from the original DNS specifications. RFC 1034 describes how CNAME records work and how resolvers process them. Operational guidance is made explicit in RFC 1912, Section 2.4:

A CNAME record is not allowed to coexist with any other data.

The reason is architectural. A CNAME doesn't contain data the way an A or MX record does. It says, "this name is an alias for another host." If other records existed alongside a CNAME, resolvers would face conflicting instructions: follow the alias, or use the local data? The protocol can't do both.

Your root domain, example.com, must have two records to function at all:

SOA (Start of Authority): Defines who manages the zone and controls how often it refreshes
NS (Name Server): Points to the nameservers that answer queries for your domain

These aren't optional. Without them, your domain doesn't exist on the internet. Trying to add a CNAME to example.com asks DNS to simultaneously "ignore this name and look elsewhere" and "use these nameservers." That's a contradiction the protocol won't resolve.

There's another consequence worth calling out: email. Your root domain needs MX records to receive mail at user@example.com. Add a CNAME, and those MX records become invalid. Email stops working.

The practical impact hits hardest when you're deploying to platforms like Vercel, Netlify, or GitHub Pages. They give you a hostname like your-project.vercel.app and tell you to point your domain there. For www.example.com, that works fine. For example.com, you're forced to choose between:

An A record that breaks when the platform changes IPs
Redirecting all traffic from example.com to www.example.com, losing the clean root URL
Giving up on the root domain entirely

None of those options are good.

How name.com's ANAME Record Solves This

name.com solves this with the ANAME record. It's not part of the DNS specification. It's a feature that name.com's nameservers provide specifically to work around the zone apex limitation.

Here's how it works:

You create an ANAME record in the name.com dashboard pointing to your target hostname, like app.platform.com
name.com's nameservers periodically resolve that hostname to get its current IP address
When a query comes in for your domain, name.com returns that IP as a standard A record
To the rest of the internet, you have a normal A record. But it updates automatically whenever the target hostname changes IPs.

From the browser's perspective, this is a single-step lookup. You get the speed of an A record with the flexibility of a CNAME.

Configuring an ANAME record:

Log in to your name.com account
Navigate to your domain's DNS settings
Add a new record with these settings:
- Type: ANAME
- Host: @ (represents your root domain)
- Answer: your-app.platform.com (your target hostname)
- TTL: 300 (5 minutes, allowing quick updates)
Save the record

The record goes live within minutes. name.com handles the resolution in the background, checking for IP changes at regular intervals and updating the served A record automatically. Understanding domain propagation will tell you when your changes are visible globally.

The key benefit: you can now point your root domain at a hostname that might change IPs, without violating DNS protocol rules or breaking your email. Your SOA and NS records stay in place, your MX records keep working, and users reach your site at example.com without the www. You can also read more about bare CNAME records and how name.com handles them.

This is the same concept that Cloudflare calls "CNAME Flattening" and AWS Route53 calls an "Alias" record. The implementation differs, but the goal is identical: solve the zone apex CNAME problem.

Common Pitfalls and Conflicts

Even when you're using CNAMEs correctly on subdomains, a few edge cases will break your setup if you're not careful.

MX Records and Wildcard CNAMEs

A common concern is whether a wildcard CNAME conflicts with your email configuration. Consider this setup:

*.example.com.    300    IN    CNAME    your-app.platform.com.
mail.example.com. 300    IN    MX       10 mail-server.com.

This configuration is actually valid.

The CNAME exclusivity rule applies per name, not per wildcard scope. *.example.com and mail.example.com are different owner names in the zone. According to RFC 4592, a wildcard record is only used when no explicit record exists for the queried name. Because mail.example.com has its own MX record, the wildcard CNAME doesn't apply to it.

Problems occur when you attach a CNAME and another record type to the exact same name:

mail.example.com. 300 IN CNAME app.platform.com.
mail.example.com. 300 IN MX    10 mail-server.com.

This is invalid. A name with a CNAME must not have any other records at that same label.

One more thing worth knowing: the host specified in an MX record must ultimately resolve to an A or AAAA record. If mail.example.com is listed as an MX target, it needs its own address record.

TXT Record Conflicts

You can't add a TXT record to a name that already has a CNAME. The exclusivity rule applies to all record types, not just A and MX.

# This is invalid:
app.example.com.    300    IN    CNAME    platform.com.
app.example.com.    300    IN    TXT      "verification-code-123"

This causes real problems when a service asks you to verify domain ownership by adding a TXT record to a subdomain that already points to a platform via CNAME. The DNS provider will reject the TXT record outright.

Common workarounds include:

Verifying the root domain (example.com) instead
Using a provider-specific verification name like _verification.example.com
Verifying a different subdomain that isn't already aliased with a CNAME

The rule is simple: if a record is a CNAME, it can't hold any other record types at the same label.

CNAME Loops

Circular references cause queries to fail entirely.

# This creates an infinite loop:
a.example.com.    300    IN    CNAME    b.example.com.
b.example.com.    300    IN    CNAME    a.example.com.

When a resolver tries to look up a.example.com, it follows the CNAME to b.example.com, which points back to a.example.com. Most resolvers detect this after a few iterations and return an error. The site becomes unreachable.

This seems obvious in a two-record example, but it happens accidentally in complex setups where subdomains point to other subdomains across different zones. Always trace the full chain before deploying changes. Use the DNS connectivity troubleshooting tools to verify your configuration before pushing it live.

Long CNAME Chains

While not technically invalid, long CNAME chains hurt performance.

# Each step adds latency:
app.example.com.        300    IN    CNAME    lb.platform.com.
lb.platform.com.        300    IN    CNAME    region-us.platform.com.
region-us.platform.com. 300    IN    A        203.0.113.45

That's three DNS lookups instead of one. Each lookup can take 50-100ms depending on network conditions. For users on mobile networks or in regions far from your nameservers, this adds up fast. Keep CNAME chains as short as possible.

Choosing the Right Record Type

Here's a quick reference for the most common scenarios:

Scenario	Record Type	Example
Subdomain pointing to IP address	A Record	`blog.example.com` → `203.0.113.45`
Subdomain pointing to hostname	CNAME	`blog.example.com` → `app.platform.com`
Root domain pointing to IP address	A Record	`example.com` → `203.0.113.45`
Root domain pointing to hostname	ANAME	`example.com` → `app.platform.com`
IPv6 address	AAAA Record	`example.com` → `2001:0db8::1`
Email server	MX Record	`example.com` → `mail.example.com`
Domain verification	TXT Record	`example.com` → `"verification-code"`

A quick checklist before you push any DNS changes:

If the record is for your root domain and needs to point to a hostname, use an ANAME
If the record is for a subdomain that also needs MX or TXT records, use an A record instead of a CNAME
If you're setting up a wildcard catch-all, confirm it doesn't conflict with specific subdomains you need for email or domain verification
If your platform (Heroku, Vercel, Netlify) provides both a hostname and IP addresses, prefer the hostname with an ANAME or CNAME so you get automatic updates

The most common mistake is trying to use a CNAME at the root domain. The second most common is using a CNAME on a subdomain that also needs to receive email. Both come from the same RFC 1034 rule: CNAMEs must be the only record for that name.

For developers automating DNS management, the name.com API gives you programmatic access to create DNS records, update records, and list all records for your domains without touching the dashboard.

Final Thoughts

CNAMEs follow strict protocol-level rules that made sense in 1987 and still make sense today, even if they create friction in modern workflows. The zone apex restriction exists because your root domain requires SOA and NS records to function, and a CNAME can't legally coexist with those records.

name.com's ANAME records handle the resolution on name.com's nameservers and serve the result as a standard A record. You get automatic IP updates when your platform changes infrastructure, with no protocol violations and no conflicts with your MX or NS records. It's a clean solution to a problem that trips up a lot of engineers the first time they encounter it.

How to Build a Domain Registration Integration with Python and the name.com API

Jakkie Koekemoer — Sat, 21 Mar 2026 15:04:41 +0000

If you're building an app that lets users pick a custom domain, you have two options. You can send them off to a registrar's website and hope they come back. Or you can handle the whole flow yourself. Platforms like Vercel, Replit, and Netlify chose the second path. They integrated domain search, registration, and DNS management directly into their products, using name.com as the backend registrar to power it all.

This guide shows you how to build that same integration. We'll walk through the complete domain lifecycle: authentication, availability search, registration, and DNS configuration, using the name.com API. Python with the requests library is the primary language here, because it's the clearest way to show what's actually happening over the wire. That said, the same concepts apply in most languages, and you'll find equivalent code blocks in PHP, Node.js, and Ruby throughout.

A quick note on scope: each language has its own conventions for package management and environment variable handling, but those details are out of scope here. Only the necessary code snippets are included.

By the end, you'll have a working Domain Manager script that covers the full lifecycle in under 200 lines. No heavy SDK to install. No XML to parse. Just HTTP calls and JSON responses.

Here's the lifecycle we're building:

Section 1: Prerequisites and Authentication

Getting Your API Credentials

Before you write a single line of code, you need two things: your name.com username and an API token. Log in to your account, navigate to the API settings page via API > API Token Management, and generate a new token. The username is the same one you use to log in, not your email address.

Name.com provides a separate test environment at https://api.dev.name.com, which runs on a different set of credentials you create at www.name.com/reseller. I'd strongly recommend starting there. Accidentally registering a live domain while debugging your error handling is an expensive way to learn a lesson.

Store your credentials as environment variables. Never hardcode them in source files.

# .env file (add this to .gitignore)
NAMECOM_USERNAME=your_username
NAMECOM_API_TOKEN=your_api_token
NAMECOM_API_URL=https://api.dev.name.com  # switch to api.name.com/ for production

The "Hello World" Request

The name.com API uses HTTP Basic Auth. Your username goes in as the username, your API token as the password. No OAuth dance, no token exchange. Just a standard header that requests handles in one line.

Here's a minimal client class that verifies your credentials are working:

Python

import os
import requests
from dotenv import load_dotenv

load_dotenv()

class NameComClient:
    def __init__(self):
        self.base_url = os.environ["NAMECOM_API_URL"]
        self.auth = (
            os.environ["NAMECOM_USERNAME"],
            os.environ["NAMECOM_API_TOKEN"]
        )
        self.headers = {"Content-Type": "application/json"}

    def hello(self):
        """Verify credentials by calling the hello endpoint."""
        response = requests.get(
            f"{self.base_url}/core/v1/hello",
            auth=self.auth,
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

# use your new NameComClient class
client = NameComClient()
print(client.hello())

Run this and you should see your username echoed back. A 401 means your token is wrong. A 404 means the base URL is off.

PHP (GuzzleHttp)

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/');
$dotenv->load();

$client = new Client([
    'base_uri' => $_ENV['NAMECOM_API_URL'],
    'auth' => [$_ENV['NAMECOM_USERNAME'], $_ENV['NAMECOM_API_TOKEN']],
    'headers' => ['Content-Type' => 'application/json'],
]);

$response = $client->get('/core/v1/hello');
echo $response->getBody();

Node.js (axios)

const axios = require('axios');
require('dotenv').config();

const client = axios.create({
  baseURL: process.env.NAMECOM_API_URL,
  auth: {
    username: process.env.NAMECOM_USERNAME,
    password: process.env.NAMECOM_API_TOKEN,
  },
  headers: { 'Content-Type': 'application/json' },
});

client.get('/core/v1/hello').then(res => console.log(res.data));

Ruby (Faraday)

require 'faraday'
require 'dotenv/load'
require 'json'

conn = Faraday.new(url: ENV['NAMECOM_API_URL']) do |f|
  f.request :authorization, :basic, ENV['NAMECOM_USERNAME'], ENV['NAMECOM_API_TOKEN']
  f.headers['Content-Type'] = 'application/json'
end

response = conn.get('/core/v1/hello')
puts JSON.parse(response.body)

Notice what's missing from every one of these examples. No SDK import. No proprietary client library. No 50-page setup guide. You're using the standard HTTP library for your language of choice, with basic authentication. It doesn't get more straightforward than that.

Section 2: Checking Domain Availability (The Search Pattern)

The Endpoint and What It Returns

Domain availability is a POST call to the /domains:search endpoint. You POST a keyword, and name.com returns a list of domain suggestions with their availability status and pricing. The price data is why this matters. You don't just need to know if a domain is available, you need to know what it costs before you show it to a user.

The response distinguishes between standard and premium domains. A premium domain like car.com might run $50,000 at registration, while mycoolstartup.com will cost considerably less. Your code needs to handle both cases, or you'll accidentally surface $50,000 domains to users expecting standard pricing.

Python Walkthrough

Add this method to your NameComClient class:

def search_domains(self, keyword: str, tlds: list = None) -> list:
        """
        Search for available domains matching a keyword.
        Returns a list of available domain options with pricing.
        """
        if tlds is None:
            tlds = ["com", "net", "org", "io"]

        payload = {
            "keyword": keyword,
            "tldFilter": tlds,
            "timeout": 10000  # milliseconds to wait for results
        }

        response = requests.post(
            f"{self.base_url}/core/v1/:domains:search",
            auth=self.auth,
            headers=self.headers,
            json=payload
        )
        response.raise_for_status()
        data = response.json()

        results = []

        for result in data.get("results", []):
            domain_info = {
                "domain": result["domainName"],
                "available": result.get("purchasable", False),
                "price": result.get("purchasePrice", 0),
                "premium": result.get("premium", False),
            }

            # Flag premium domains clearly — they can cost orders of magnitude more
            if domain_info["premium"]:
                domain_info["premium_price"] = result.get("premiumRenewalPrice")

            if domain_info["available"]:
                results.append(domain_info)

        return results

To use it:

# search available domains
client = NameComClient()
results = client.search_domains("mycoolstartup")
for r in results:
    status = "[PREMIUM]" if r["premium"] else ""
    print(f"{r['domain']}: ${r['price']:.2f}/year {status}")

This returns all domains that are available and match or are similar to your keyword. The purchasable field is your source of truth for availability. The purchasePrice is in dollars. Premium domains will have "premium": true. Filter those out or handle them separately depending on your use case.

PHP

function searchDomains(Client $client, string $keyword, array $tlds = ['com', 'net', 'io']): array {
    $response = $client->post('/core/v1/domains:search', [
        'json' => ['keyword' => $keyword, 'tldFilter' => $tlds, 'timeout' => 10000],
    ]);
    $data = json_decode($response->getBody(), true);
    return (array_filter($data['results'] ?? [], fn($r) => $r['purchasable'] && !$r['premium']));
}

// Use your new function
print_r(searchDomains($client, 'mycoolstartup'));

Node.js

async function searchDomains(keyword, tlds = ['com', 'net', 'io']) {
  const { data } = await client.post('/core/v1/domains:search', {
    keyword,
    tldFilter: tlds,
    timeout: 10000,
  });
  return (data.results || []).filter(r => r.purchasable && !r.premium);
}

// Use your new function
(async () => {
  const result = await searchDomains('mycoolstartup'); // Pause until the Promise resolves
  console.log(result); // Logs "Resolved data"
})();

Ruby

def search_domains(conn, keyword, tlds = ['com', 'net', 'io'])
  response = conn.post('/core/v1/domains:search') do |req|
    req.body = { keyword: keyword, tldFilter: tlds, timeout: 10_000 }.to_json
  end
  data = JSON.parse(response.body)
  (data['results'] || []).select { |r| r['purchasable'] && !r['premium'] }
end

# Use your new function
result = search_domains(conn, 'mycoolstartup')
puts result

Section 3: Domain Registration (The Transaction)

What Domain Registration Actually Requires

This is where things get more complex. Registering a domain isn't just naming it. ICANN requires contact information for four roles: Registrant, Admin, Tech, and Billing. Each contact needs a name, organization, address, phone number, and email. In most cases, all four roles will be the same person. If not, you'll need to expand the code to accept a different contact object for each role.

Python Walkthrough

Add this method to your NameComClient class:

   def register_domain(self, domain_name: str, contact_details: dict, years: int = 1) -> dict:
        """
        Register a domain 
        """
        payload = { 
            "domain": {
                "domainName": domain_name,
                "years": years,
                    "contacts": { 
                        "tech": {
                            "firstName": contact_details['firstName'],
                            "lastName": contact_details['lastName'],
                            "companyName": contact_details['companyName'],
                            "address1": contact_details['address1'],
                            "address2": contact_details['address2'],
                            "city": contact_details['city'],
                            "state": contact_details['state'],
                            "zip": contact_details['zip'],
                            "country": contact_details['country'],
                            "email": contact_details['email'],
                            "phone": contact_details['phone']
                        }
                    },
                    "privacyEnabled": True
                } 
            }

        try:
            response = requests.post(
                f"{self.base_url}/core/v1/domains",
                auth=self.auth,
                headers=self.headers,
                json=payload
            )
            response.raise_for_status()
            return response.json()

        except requests.exceptions.HTTPError as e:
            error_data = e.response.text

            raise ValueError(f"An error has occured while trying to register: {domain_name}\nThe error is: {error_data}")

To use it:

client = NameComClient()
contact1 = {
    "firstName": "Jonny",
    "lastName": "IT Guy",
    "companyName": "My Company",
    "address1": "1234 Any Street",
    "address2": "None",
    "city": "Anytown",
    "state": "NY",
    "zip": "11222",
    "country": "US",
    "email": "support@example.com",
    "phone": "+15555555"
}
try:
    result = client.register_domain("mycoolstartup.com", contact_details=contact1)
    print(f"Registered: {result['domain']['domainName']} — expires {result['domain']['expireDate']}")
except ValueError as e:
    print(f"Cannot register: {e}")

A 409 Conflict response means the domain was taken between your availability check and your registration attempt. It happens.

PHP

function registerDomain(Client $client, string $domain, array $contact_details, int $years): array {
    try {
        $response = $client->post('/core/v1/domains', [
            'json' => [
                "domain" => [
                    "domainName" => $domain,
                    "years" => $years,
                    "contacts" => [
                        "tech" => [
                            "firstName" => $contact_details['firstName'],
                            "lastName" => $contact_details['lastName'],
                            "companyName" => $contact_details['companyName'],
                            "address1" => $contact_details['address1'],
                            "address2" => $contact_details['address2'],
                            "city" => $contact_details['city'],
                            "state" => $contact_details['state'],
                            "zip" => $contact_details['zip'],
                            "country" => $contact_details['country'],
                            "email" => $contact_details['email'],
                            "phone" => $contact_details['phone'],
                        ],
                    ],
                    "privacyEnabled" => 1,
                ],
            ],
        ]);
        return json_decode($response->getBody(), true);
    } catch (\GuzzleHttp\Exception\ClientException $e) {
        $body = json_decode($e->getResponse()->getBody(), true);
        throw new \RuntimeException('Registration failed: ' . ($body['message'] ?? 'unknown'));
    }
}

// Use your new function:
$contact_details = [
    "firstName" => "Jonny",
    "lastName" => "IT Guy",
    "companyName" => "My Company",
    "address1" => "1234 Any Street",
    "address2" => "None",
    "city" => "Anytown",
    "state" => "NY",
    "zip" => "11222",
    "country" => "US",
    "email" => "support@example.com",
    "phone" => "+15555555",
];

print_r(registerDomain($client, 'mycoolstartup.com', $contact_details, 1));

Node.js

async function registerDomain(domainName, contact_details, years) {
  try {
    const { data } = await client.post('/core/v1/domains', {
      domain: {
        domainName: domainName,
        years: years,
        contacts: {
          tech: {
            firstName:   contact_details.firstName,
            lastName:    contact_details.lastName,
            companyName: contact_details.companyName,
            address1:    contact_details.address1,
            address2:    contact_details.address2,
            city:        contact_details.city,
            state:       contact_details.state,
            zip:         contact_details.zip,
            country:     contact_details.country,
            email:       contact_details.email,
            phone:       contact_details.phone
          }
        },
        privacyEnabled: true
      }
    });
    return data;
  } catch (err) {
    const message = err.response?.data?.message || 'Unknown error';
    throw new Error(`Registration failed: ${message}`);
  }
}

// Use your new function
let contact1 = {
    "firstName": "Jonny",
    "lastName": "IT Guy",
    "companyName": "My Company",
    "address1": "1234 Any Street",
    "address2": "None",
    "city": "Anytown",
    "state": "NY",
    "zip": "11222",
    "country": "US",
    "email": "support@example.com",
    "phone": "+15555555"
};

(async () => {
  const result = await registerDomain('mycoolstartup.com', contact1, 1); // Pause until the Promise resolves
  console.log(result); // Logs "Resolved data"
})();

Ruby

def register_domain(conn, domain_name, contact_details, years)
  payload = {
    domain: {
        domainName: domain_name,
        years: years,
        contacts: {
          tech: {
            firstName:   contact_details[:firstName],
            lastName:    contact_details[:lastName],
            companyName: contact_details[:companyName],
            address1:    contact_details[:address1],
            address2:    contact_details[:address2],
            city:        contact_details[:city],
            state:       contact_details[:state],
            zip:         contact_details[:zip],
            country:     contact_details[:country],
            email:       contact_details[:email],
            phone:       contact_details[:phone]
          }
        },
        privacyEnabled: true
      }
    }
  response = conn.post('/core/v1/domains') { |req| req.body = payload.to_json }
  raise "Registration failed: #{JSON.parse(response.body)['message']}" unless response.status == 200
  JSON.parse(response.body)
end

# Use your new function
contact1 = {
    firstName: "Jonny",
    lastName: "IT Guy",
    companyName: "My Company",
    address1: "1234 Any Street",
    address2: "None",
    city: "Anytown",
    state: "NY",
    zip: "11222",
    country: "US",
    email: "support@example.com",
    phone: "+15555555"
}

result = register_domain(conn, 'mycoolstartup.com', contact1, 1)
puts result

Section 4: Managing DNS Records (The Configuration)

The Scenario

You've registered mycoolstartup.com. Now you need to point it at your server at 192.168.113.42. That means creating an A record with a TTL of 300 seconds. Here's how to do it programmatically.

Listing Existing DNS Records

Before you add records, check what's already there. Name.com sets up default nameserver records when you register a domain, and you don't want to create conflicts.

Add this method to your NameComClient class:

def list_dns_records(self, domain_name: str) -> list:
        """List all DNS records for a domain."""
        response = requests.get(
            f"{self.base_url}/core/v1/domains/{domain_name}/records",
            auth=self.auth,
            headers=self.headers
        )
        response.raise_for_status()
        return response.json().get("records", [])

# Use your new function
client = NameComClient()
records = client.list_dns_records("mycoolstartup.com")
for record in records:
    print(f"{record['type']} {record['host']} -> {record['answer']}")

Creating an A Record

def point_to_ip(self, domain_name: str, ip_address: str, host: str = "") -> dict:
    """
    Create an A record pointing a domain (or subdomain) to an IP address.
    host="" targets the apex domain (@).
    host="www" targets www.mycoolstartup.com.
    """
    payload = {
        "host": host,
        "type": "A",
        "answer": ip_address,
        "ttl": 300,  # 5-minute TTL, sensible default, fast to propagate
    }

    response = requests.post(
        f"{self.base_url}/core/v1/domains/{domain_name}/records",
        auth=self.auth,
        headers=self.headers,
        json=payload
    )
    response.raise_for_status()
    return response.json()

# Usage: point www to the new server
client = NameComClient()
client.point_to_ip("mycoolstartup.com", "192.168.113.42", host="www")
print("A record created. DNS will propagate within ~10 minutes.")

PHP

function point_to_ip(Client $client, string $domain, string $ip, string $host = ''): array {
    $response = $client->post("/core/v1/domains/{$domain}/records", [
        'json' => ['host' => $host, 'type' => 'A', 'answer' => $ip, 'ttl' => 300],
    ]);
    return json_decode($response->getBody(), true);
}

// Use your new function
print_r(point_to_ip($client, 'mycoolstartup.com', '192.168.113.42', 'www'));

Node.js

async function point_to_ip(domainName, ip, host = '') {
  const { data } = await client.post(`/core/v1/domains/${domainName}/records`, {
    host, type: 'A', answer: ip, ttl: 300,
  });
  return data;
}

// Use your new function
(async () => {
  const result = await point_to_ip('mycoolstartup.com', '192.168.13.42', 'www'); // Pause until the Promise resolves
  console.log(result); // Logs "Resolved data"
})();

Ruby

def point_to_ip(conn, domain_name, ip, host = '')
  response = conn.post("/core/v1/domains/#{domain_name}/records") do |req|
    req.body = { host: host, type: 'A', answer: ip, ttl: 300 }.to_json
  end
  JSON.parse(response.body)
end

# Use your new function
result = point_to_ip(conn, 'mycoolstartup.com', '192.168.13.42', 'www')
puts result

Beyond A records, you can create CNAME, MX, TXT, and NS records using the same endpoint. Just swap the type field and set answer accordingly. A TXT record for domain verification with Google Search Console or Mailgun follows the exact same pattern with "type": "TXT".

Section 5: Common Domain API Integration Patterns

Handling Rate Limits

The name.com API returns 429 Too Many Requests if you send too many calls in a short window. This probably won't come up in a standard single-user UI flow, but it gets real quickly when you're running bulk operations like checking hundreds of domains at once.

The simplest fix is a retry loop with exponential backoff:

import time

def api_request_with_retry(self, method: str, endpoint: str, **kwargs) -> dict:
    """Make an API request with automatic retry on rate limiting."""
    max_retries = 3
    for attempt in range(max_retries):
        response = requests.request(
            method,
            f"{self.base_url}/core/v1/{endpoint}",
            auth=self.auth,
            headers=self.headers,
            **kwargs
        )
        if response.status_code == 429:
            wait_seconds = 2 ** attempt  # 1s, 2s, 4s
            print(f"Rate limited. Retrying in {wait_seconds}s...")
            time.sleep(wait_seconds)
            continue
        response.raise_for_status()
        return response.json()
    raise RuntimeError("Max retries exceeded after rate limiting.")

For bulk domain checks, say you're building a feature that checks 50 TLD variants of a brand name, keep your batch size under 20 per request and add a time.sleep(0.5) between calls. That's enough breathing room for most production workloads.

Name.com also supports webhooks. You can configure an endpoint to receive a notification when a domain registration completes on the registry side. That's the production-grade version of this pattern: queue the task, let name.com ping you when it's done, then update your UI.

Final Thoughts

You've just walked through the full domain lifecycle in four endpoints and fewer than 200 lines of Python. The PHP, Node.js, and Ruby versions are structurally identical: set up Basic Auth, send JSON, parse the response.

That simplicity is the point. Legacy registrar APIs like Namecheap's require XML/SOAP parsing, a format that modern JSON-native languages handle awkwardly. AWS Route 53 works, but Boto3's IAM configuration is significant overhead for a task that's fundamentally just "register a domain." The name.com RESTful JSON API means any language with a decent HTTP library can become a domain client in an afternoon.

Get your API token from your account settings and start building.

Frequently Asked Questions

What is a domain registration API?

A domain registration API is a programmatic interface that lets developers search for domain availability, register domains, and manage DNS records directly within their application, without redirecting users to a registrar's website. The name.com RESTful API exposes these capabilities over standard HTTPS with JSON request and response bodies.

Which Python library should I use for the name.com domain API?

The requests library is the clearest choice for making HTTP calls to the name.com API. It handles Basic Auth in a single line and parses JSON responses natively. No SDK or domain-specific library is required.

How do I check domain availability programmatically?

Send a POST request to /domains:search with your keyword and an optional list of TLD filters. The response includes each domain's purchasable status and purchasePrice. Filter on purchasable: true and check the premium flag before surfacing results to users. Premium domains can cost orders of magnitude more than standard registrations.

What HTTP status codes should I handle from the name.com domain API?

The most important ones: 401 Unauthorized (bad credentials), 400 Bad Request (invalid request data, usually a generic issue with the POST body), and 429 Too Many Requests (rate limit hit, implement exponential backoff).

Document Generation API: How to Automate Personalized Document Creation at Scale

Jakkie Koekemoer — Mon, 16 Mar 2026 10:14:26 +0000

Every company has the same hidden bottleneck: someone, somewhere, is manually building documents. They pull a client's name from the CRM, paste it into a Word template, double-check the date, adjust the logo placement, and export to PDF. On a good day, that's an intern handling a manageable workload. On a bad day, it's an engineer who wired the entire layout into iText or PDFKit, and now Marketing needs the font changed across every document type.

Both approaches share the same problem: they don't scale. They're manual workarounds dressed up as processes, and they collapse the moment volume jumps from a few hundred records to 50,000 invoices that need to ship overnight. Legacy Mail Merge tools hit the same wall.

There's a cleaner path. A document generation API turns document creation into a data pipeline: define the layout once in a template, feed it structured JSON, and let the API return a finished PDF or DOCX in milliseconds. No one touches the document by hand. No one copy-pastes a single field.

This article explains how that pipeline works, which industries rely on it most, and how Foxit's DocGen API makes it practical to implement, even if your team has never automated a document workflow before.

What Is a Document Generation API?

At its core, a document generation API is a cloud service that combines two inputs (a template and a data payload) to produce one output (a finished document). The template controls the visual layer: layout, fonts, branding, and placeholder tokens for dynamic content. The data comes as JSON, with keys that map directly to those placeholders. The API engine merges the two and delivers a production-ready PDF or DOCX, typically in milliseconds.

The formula is simple:

Template (Structure) + JSON Data (Content) + API Engine = Final Document

Why use an API instead of building a local renderer? Two reasons.

First, scalability. The same API call that produces one invoice can produce 100,000 invoices. You don't manage rendering servers, worry about memory pressure from complex layouts, or debug pagination edge cases. The provider handles all of that.

Second, separation of concerns. Your legal team edits a liability clause directly in the Word template; no developer involvement required. Marketing swaps the logo without triggering a code deployment. The document's appearance lives entirely outside your codebase.

Not every tool follows this model. Libraries like PDFKit and Apache PDFBox take a code-first approach: you draw lines, position text boxes, and calculate column widths programmatically. That's manageable for static, single-page documents. It falls apart when tables grow to unpredictable lengths, when conditional sections depend on customer data, or when non-technical stakeholders need to change the design. The template-based API approach solves this by keeping design decisions in Word and logic in code, each where it belongs.

How Document Generation Automation Works

The system breaks down into three layers. Understanding each one makes every integration decision clearer.

1. Template Creation

Modern document generation APIs like Foxit's don't require you to write layout code. Instead, you design the document in Microsoft Word exactly as it should appear, then drop in double-bracket tokens wherever dynamic data should go.

For an invoice template, the tokens might look like:

{{ companyName }}: the client's company name
{{ invoiceDate \@ MM/dd/yyyy }}: a formatted date like 01/15/2024
{{ totalDue \# Currency }}: a currency value like $2,500.00

The template is a standard .docx file. Anyone on the team can open it, change the header font, move the logo, or reword a paragraph. None of those changes touch your application code.

2. Data Binding

Your application fetches data from its source, whether that's a Salesforce CRM, an SAP ERP system, or a PostgreSQL database, and formats it as JSON. The JSON keys correspond directly to the token names in the template. There's no transformation layer and no intermediate format to maintain.

Here's a sample payload for the invoice template above:

{
  "companyName": "Meridian Financial Group",
  "invoiceDate": "2024-01-15",
  "invoiceNumber": "INV-00471",
  "lineItems": [
    {
      "description": "API Integration Consulting",
      "qty": 10,
      "unitPrice": 150.0
    },
    { "description": "Compliance Review", "qty": 5, "unitPrice": 200.0 }
  ],
  "totalDue": 2500.0
}

companyName, invoiceDate, and totalDue in the JSON match the tokens in the template. The binding is 1:1.

3. Dynamic Template Logic: Loops and Formatting

This is where a document generation API pulls ahead of basic find-and-replace tools.

Repeating tables use loop delimiters. In Foxit's syntax, you place {{TableStart:lineItems}} and {{TableEnd:lineItems}} around the row that should repeat. The API walks through the lineItems array in your JSON and generates one row for each entry, whether the array contains 2 items or 200. Within the loop, {{ ROW_NUMBER }} provides automatic line numbering and {{ SUM(ABOVE) }} calculates column totals.

Formatting specifiers live inside the token syntax itself. The \# Currency specifier converts 2500.00 into $2,500.00. The \@ MM/dd/yyyy specifier handles date formatting without requiring any preprocessing in your application.

The net effect: your templates handle variable-length tables, locale-aware formatting, and conditional logic entirely within Word. Your codebase stays focused on business logic, not document rendering.

Document Generation Use Cases by Industry

Several industries depend on document generation in their critical workflows. These are the scenarios where automation delivers the fastest return.

Financial Services: Client Reports and Investment Summaries

Consider a wealth management firm that produces quarterly performance reports for thousands of clients. The report template (header, chart placeholders, disclaimer, signature block) stays constant. The data varies per client: portfolio value, asset allocation, benchmark comparisons, year-to-date returns. A nightly batch job pulls each client's data from the portfolio management system, assembles JSON payloads, and sends POST requests to the generation API. By morning, 8,000 personalized PDFs sit in an Amazon S3 bucket, ready for delivery.

Insurance: The Policy Packet

When an insurance carrier issues a homeowner's policy, the output is a multi-section document: cover letter, declarations page, endorsements, and liability disclaimer. Each section can be a separate template. The API merges them into a single PDF at bind time, replacing the manual process where underwriters assembled packets by hand.

HR and Operations: Employee Onboarding

The moment a new hire accepts an offer, the HRIS fires a webhook. The document generation service picks up the employee's details (name, role, start date, salary, benefits elections) and produces the complete onboarding packet: offer letter, benefits summary, I-9 instructions, and handbook acknowledgment. The new employee receives a personalized PDF bundle within seconds. No one in HR assembled it manually.

Sales: Branded Quotes and Contracts

Sales teams know the "Export to PDF" routine: populate a spreadsheet, copy the data into Word, fix the formatting, and hope the branding holds. A document generation API replaces that entire cycle with a CRM-triggered workflow. When a rep marks a deal as "Proposal Sent," Salesforce fires a POST request with the deal data. The API returns a branded PDF with accurate pricing, the client's logo from the CRM record, and the correct contract terms for that deal tier.

Foxit DocGen: The Developer Experience

Foxit has spent over 20 years building PDF engines. Their DocGen API brings that experience to a cloud-based, word-template-to-PDF service designed for straightforward integration. The workflow has three steps.

Step 1: Design Your Word Template

Open Microsoft Word and build your document with {{ token }} placeholders using Foxit's double-bracket syntax. Add format specifiers and loop delimiters directly in the document. No proprietary editor required.

Step 2: Send a POST Request

The API endpoint is /document-generation/api/GenerateDocumentBase64. Authentication uses client_id and client_secret passed as HTTP headers. The request body contains the base64-encoded template and your JSON data. Here's the full flow in Python:

import requests
import base64

# Load and encode the Word template
with open("invoice_template.docx", "rb") as f:
    template_b64 = base64.b64encode(f.read()).decode("utf-8")

# JSON data payload from your CRM or database
document_values = {
    "companyName": "Meridian Financial Group",
    "invoiceDate": "2024-01-15",
    "invoiceNumber": "INV-00471",
    "lineItems": [
        {"description": "API Integration Consulting", "qty": 10, "unitPrice": 150.00},
        {"description": "Compliance Review", "qty": 5, "unitPrice": 200.00}
    ],
    "totalDue": 2500.00
}

# POST to Foxit DocGen API
# Replace HOST with the base URL from your Foxit developer console
response = requests.post(
    "{HOST}/document-generation/api/GenerateDocumentBase64",
    headers={
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "Content-Type": "application/json"
    },
    json={
        "base64FileString": template_b64,
        "documentValues": document_values,
        "outputFormat": "pdf"
    }
)

# Decode and save
result = response.json()
pdf_bytes = base64.b64decode(result["base64FileString"])
with open("invoice_00471.pdf", "wb") as f:
    f.write(pdf_bytes)

print("Invoice generated successfully.")

Step 3: Decode and Store the Response

The API returns a base64-encoded document in the response. Decode it, write it to disk or push it to an Amazon S3 bucket, and the job is done.

One capability worth highlighting: Foxit supports DOCX output alongside PDF. Most document generation APIs lock you into PDF, which is immutable once generated. DOCX output opens up a draft review workflow where a generated document can go to a human reviewer for light edits before finalization. That's particularly valuable in legal and HR contexts where someone needs to approve a clause or add a handwritten note. Sample code and SDKs cover Python, JavaScript, Java, C#, and PHP, with additional languages on the developer portal. A Postman workspace is also available for testing without writing any code.

Why the API Approach Beats Building It Yourself

Switching from a hand-coded PDF renderer to a template-based API delivers three concrete improvements.

Compliance and accuracy. Hard-coded PDF layouts invite human error on every update. A case mismatch between {{ CustomerName }} and {{ customerName }} silently produces blank fields. With the API approach, data flows directly from your database into the document through structured bindings. There's no manual copy-paste step where someone transposes a loan amount or miskeys a policy limit.

Speed at scale. Local rendering libraries like PDFKit process documents sequentially on your server. Rendering time increases with document complexity, especially for multi-page tables. At 10,000 documents, even small per-document delays add up to minutes of blocked processing. A cloud-based document generation API distributes rendering across managed infrastructure. Producing 50,000 invoices overnight becomes a scheduling decision, not a compute constraint.

Maintenance goes to the right people. When Marketing wants to update the invoice footer, they open the Word template and make the change themselves. When Legal revises a liability clause, they do the same. No developer writes code, no one triggers a redeployment, and no one runs regression tests because a text block moved three pixels. That's the compounding benefit of the template-first model: every design iteration happens without a developer ticket.

Final Thoughts

If your team is still manually assembling documents in Word, or maintaining a custom PDF renderer that breaks on edge cases, the template-plus-API pattern is a practical fix that doesn't require rearchitecting your system.

One trend worth keeping an eye on: combining document generation with generative AI. A few teams are already using LLMs to draft personalized narrative sections (like a portfolio summary or a client recommendation), then feeding that text as a JSON field into the document generation API. The LLM writes the prose; the API controls the formatting, branding, and layout. It's a way to get dynamic, personalized content without sacrificing consistency.

If you've gone through this transition, or you're still running a hand-rolled PDF generator, I'd be curious to hear what tipped the balance. What made your team decide to change approaches?

Dynamic Data Masking: Use Cases, Limitations, and What to Do Instead

Jakkie Koekemoer — Fri, 13 Mar 2026 16:00:36 +0000

Let’s imagine two everyday scenarios. A customer support agent pulls up an order record. They need the order history, but there's no reason for them to see the full credit card number. A developer is debugging a user profile issue, but shouldn't have access to the actual customer's email address.

The common solution for this is Dynamic Data Masking (DDM). Instead of the real credit card number, the database shows ****-****-****-3456. Instead of the real email, it shows j***@email.com.

You can think of DDM as a filter sitting between your database and the user querying it. The underlying data stays untouched, DDM just controls what different users get to see. For customer support teams working with live data, it works well since you don't want them to see the sensitive details. But for engineering and development teams, it tends to create more problems than it solves because masked data can break query logic, skew test results, and make it harder to reproduce real bugs accurately. If you're deciding how to protect sensitive data in your development workflow, understanding that distinction matters a lot.

What is Dynamic Data Masking?

Dynamic Data Masking modifies data at query time based on your DB policies. The underlying data stays intact on disk. When someone queries a table, the database engine intercepts the SELECT and rewrites the output before returning results.

The diagram below shows this flow:

Microsoft SQL Server implements DDM using column-level masking functions defined in the schema:

-- Define masked columns directly in schema
CREATE TABLE customers (
    id INT PRIMARY KEY,
    email VARCHAR(50) MASKED WITH (FUNCTION = 'email()'),
    credit_card VARCHAR(16) MASKED WITH (FUNCTION = 'partial(0,"XXXX-XXXX-XXXX-",4)')
);

-- Grant unmask permission for specific roles
GRANT UNMASK ON customers(email) TO support_role;

PostgreSQL Anonymizer uses security labels to define rules:

-- You need the PostgreSQL Anonymizer extension installed and enabled
-- Mark columns with masking functions
SECURITY LABEL FOR anon ON COLUMN customer.email 
  IS 'MASKED WITH FUNCTION anon.fake_email()';

-- Enable transparent masking for specific roles
SECURITY LABEL FOR anon ON ROLE analyst IS 'MASKED';

There are three common patterns for DDM masking:

Full masking replaces the entire value — so john.doe@email.com becomes NULL or *****.
Partial masking hides only the sensitive part — so 1234-5678-9012-3456 becomes xxxx-xxxx-xxxx-3456.
Randomization swaps the real value with fake but realistic-looking data, so "John Smith" might become "Robert Johnson", from a dictionary of fake names.

It's important to understand that your database still runs all queries against the real, unmasked data. JOINs, aggregations, and WHERE filters all work on the actual values in your RDBMS tables. Masking only takes place at the very end, just before the results are sent back to the relevant user.

Dynamic vs. Static Data Masking

With Dynamic Data Masking, the original data stays untouched in your database. Masking happens on the fly when data is retrieved, and what users see depends on their permissions. On the other hand, Static Data Masking works differently: it permanently transforms the data itself, creating a separate sanitized copy of the database where sensitive values are replaced with fake or masked data.

That architectural difference determines which approach fits your situation. The diagram below shows both:

Dynamic Data Masking transforms data in flight

Advantages: You're always working with current production data. There's no extra storage needed, and you maintain a single source of truth.

Disadvantages: It adds CPU overhead of 2-10% per query at runtime. Managing role-based access control can get complex. And it's fundamentally vulnerable to inference attacks: where someone deduces sensitive information by analyzing patterns in the data they can see.

Best for: Production operational access, customer support dashboards, and read-only reporting where users can't write their own arbitrary queries.

Static Data Masking transforms data at rest

Advantages: No runtime overhead once the initial transformation is done. It's immune to inference attacks since the sensitive data is replaced entirely. And it's safe to share freely with developers.

Disadvantages: Historically, creating a full masked copy of your database could take hours. The data starts going stale the moment the copy is created. And setting up the ETL pipeline adds its own layer of complexity.

Best for: Development environments, staging databases, testing, and QA. Basically any scenario where developers need write access or the ability to run ad hoc queries.

Static masking has long had a staleness problem though. If generating a masked copy of a 200GB database takes 4 hours, your developers are waiting half a day just to get test data. And by the time that copy is ready, production has already moved on. That delay is a big reason why many teams turned to DDM for development workflows, even knowing its security tradeoffs.

The Problem with DDM for Developers

Here's what Microsoft's documentation warns about DDM explicitly:

"Dynamic data masking (DDM) doesn't aim to prevent database users from connecting directly to the database and running exhaustive queries that expose pieces of the sensitive data."

Oracle's security guide says the same thing:

"Oracle Data Redaction is not intended to protect against attacks by regular and privileged database users who run ad hoc queries directly against the database."

The core issue is that WHERE clauses always run against the real, unmasked values. Only the output the user sees gets masked. That gap is exactly what makes inference attacks possible, and the diagram below shows how they work:

To see this in practice, consider a salary column masked to show zero. You run:

SELECT name, salary 
FROM employees 
WHERE salary > 99999 AND salary < 100001;

The result returns "Jane Doe" with her salary showing as 0. But you already know what that means: Jane earns $100,000. Take this further with a binary search approach, and just 20 queries are enough to pinpoint any value within a million-dollar range down to the exact dollar.

String columns leak through character-by-character extraction:

-- Find first character
SELECT name FROM customers WHERE email LIKE 'a%';  -- No results
SELECT name FROM customers WHERE email LIKE 'b%';  -- No results
SELECT name FROM customers WHERE email LIKE 'j%';  -- Returns "Customer 1"

-- Find second character
SELECT name FROM customers WHERE email LIKE 'ja%'; -- No results
SELECT name FROM customers WHERE email LIKE 'jo%'; -- Returns "Customer 1"

A 24-character email requires roughly 6,000 iterations, and scripts can easily automate this.

Aggregate functions disclose data regardless of masking:

-- Both return actual sum, even though individual salaries show as 0
SELECT SUM(salary) FROM employees WHERE department = 'Engineering';
SELECT AVG(salary) FROM employees WHERE job_title = 'Senior Engineer';

ORDER BY reveals relative rankings even when values display as masked. Someone with the highest salary appears first in ORDER BY salary DESC regardless of what the salary column shows.

This isn't a bug, it's a documented design decision. DDM is built to prevent accidental exposure in controlled, read-only contexts. It was never meant to protect against users who can query the database directly. And since developers write and run SQL queries against database tables, DDM simply can't protect sensitive data from them.

Beyond DDM: Copy-on-Write Branching

Copy-on-write branching is a storage technique that creates instant snapshots of your database. Instead of duplicating the entire dataset upfront, it only copies data when it's actually modified. This solves the staleness problem by making a "static" copy available instantly. Tools like Xata implement this at the database level, giving you the security benefits of static masking with the speed that makes developers actually use it.

The diagram below shows this approach:

Here's how it works: Creating a branch instantiates a logical copy that initially shares all physical data pages with its parent. No data moves. A 200GB database branch creates in 30 seconds regardless of size. When you modify data in the branch, only changed pages consume additional storage.

A secure development workflow looks like this:

Create a "golden" parent branch from production
Apply static masking to this parent (happens once)
Create child branches from the masked parent for developers or CI/CD
Developers get full read/write access to realistic data
Delete branches when done, storage reclaims immediately

Developers get to work with actual production data patterns. Foreign keys work. Query performance matches production. Edge cases surface during testing instead of production incidents. But no unmasked sensitive data exists anywhere in the non-production environment.

The security gain: Inference attacks fail with this approach because sensitive data is physically absent. No cleartext values exist to infer through WHERE clauses, JOINs, or backup files. That's a meaningful improvement over DDM, where the database always contains unmasked data regardless of access controls.

Xata's data anonymization integrates directly into this branching workflow:

# Create anonymized branch from production
xata branch create dev-branch --from main --anonymize

# Branch ready in seconds with:
# - All PII masked deterministically (referential integrity preserved)
# - Realistic data distributions maintained
# - Full read/write access for testing

Where this approach proves most useful

Let's say a production bug is impacting three specific customers. With DDM, handing developers access to investigate isn't really a safe option. But with copy-on-write branches, you can spin up an anonymized copy with just the relevant records in about 30 seconds. Developers can dig into real, realistic data, and once they're done, the branch is simply deleted. Production stays off-limits and no PII ever gets exposed.

Where traditional static masking used to mean waiting through 4-hour ETL jobs, modern copy-on-write branching gets you a fully masked environment in half a minute. You get the security guarantees of physically transforming the data, at a speed that developers will actually enjoy working with.

Best Practices for Implementation

Step 1: Identify your PII

Start by cataloging every column that holds sensitive data. This includes the obvious ones like names, emails, phone numbers, addresses, payment details, and health records, but also any regulatory-defined identifiers. Don't overlook derived fields either: usernames sometimes embed real names, and session logs can contain PII buried in URLs.

For a comprehensive definition of what counts as PII, GDPR is a good reference. It covers genetic data, biometric data, location data, and online identifiers like IP addresses and cookies. The CCPA goes further, extending coverage to commercial information and internet activity.

Step 2: Define roles and access patterns

Think through which users actually need to see which data. Support agents might need the last four digits of a credit card for verification, but never the full number. Analysts need aggregated statistics, not individual customer records. Developers need data that looks and behaves realistically, but not real customer information.

A useful way to think about this: separate your read-only operational users like support staff and analysts from your query-capable users like developers and data scientists. DDM can work reasonably well for the first group. For the second group, it's not a safe option.

Step 3: Choose the right tool

The flowchart below guides how to effectively protect sensitive data with static or dynamic masking:

Use DDM for production operational access when:

Users only interact with data through controlled applications
There's no ability to run ad hoc queries
Read-only access is all that's needed
You can audit every data access request

Use anonymized branches for development when:

Developers need to write and run their own queries
Write access is required
Integration testing needs referential integrity to hold up
You want to remove any possibility of inference attacks

You can also use both together. DDM handles protection on the production side for operational users, while copy-on-write branches give developers and staging environments a safe place to work. These two masking approaches solve two different problems.

Step 4: Set up security monitoring

Keep an eye on data access patterns so you can catch inference attacks early. Some things worth watching for:

Repeated similar queries where the WHERE clause value keeps incrementing
A high volume of queries that each return just a single row
Aggregate queries that target unusually small subsets of data
Pattern matching queries with systematic character variations

PostgreSQL's audit extensions and AWS RDS audit logs can both help you capture and analyze these patterns.

Conclusion

Dynamic Data Masking (DDM) has a clear and specific purpose: keeping sensitive data from being accidentally exposed in read-only, application-controlled production scenarios. So it is ideal for customer support dashboards, operational reporting, or any context where users interact with data through fixed interfaces and can't run their own queries.

Where it falls short is with developers. Because developers write and run queries directly, WHERE clauses, aggregations, and inference attacks can pull out masked values no matter how DDM is configured. Development environments need write access and query freedom, which means DDM is a poor fit there by design.

Real security for development workflows means giving developers safe data to work with, not just hiding unsafe data behind a filter. Storage-layer approaches that combine copy-on-write branching with static masking give you both: the data is physically transformed so it's genuinely secure, and masked environments are ready in about 30 seconds. Traditional static masking had the security part right but killed developer velocity with hours-long ETL jobs. Modern branching tools solve both sides of that tradeoff, and if your team is still leaning on DDM to protect development environments, they're worth a serious look.

Automate DNS Management with the name.com API

Jakkie Koekemoer — Thu, 05 Mar 2026 17:38:04 +0000

Infrastructure as Code has changed how engineering teams manage servers, databases, and networks. But DNS is still a manual bottleneck for a lot of teams. You log into a dashboard, click through forms, and hope you don't fat-finger a record mid-deployment.

That works fine when you're managing a handful of domains. It stops working when you're juggling dozens of domains, spinning up ephemeral environments, or coordinating deployments across multiple services.

The name.com API is the fix. It's a REST API that lets you programmatically search, register, and manage your DNS records. Unlike registrars that bolt on API access as an enterprise upsell or an afterthought, name.com provides API access as a core feature, with standard HTTP methods, JSON responses, and real documentation.

By the end, you'll have the building blocks for DNS automation that can be triggered directly from your CI/CD pipeline.

Authentication and Security

API access starts in your name.com dashboard. Navigate to API, then API Token Management. You get two environments: production (api.name.com) and development/test (api.dev.name.com). The test environment uses your username with -test appended and a separate token. This lets you safely test DNS changes without touching live domains.

The API uses HTTP Basic Auth. Your username and token combine into a base64-encoded header. Here's how to construct it:

import base64

# Environment variables for credentials
username = os.getenv('NAMECOM_USERNAME')
token = os.getenv('NAMECOM_TOKEN')

# Construct the Basic Auth header
credentials = f"{username}:{token}"
encoded_credentials = base64.b64encode(credentials.encode()).decode()
auth_header = f"Basic {encoded_credentials}"

# Use in requests
headers = {
    'Authorization': auth_header,
    'Content-Type': 'application/json'
}

Always include this header in your API requests.

Never hardcode credentials in scripts. Use environment variables or a secrets manager like AWS Secrets Manager, HashiCorp Vault, or your CI/CD platform's native secrets feature. A .env file works for local development, but add it to .gitignore immediately.

For team environments, rotate tokens on a regular schedule. Name.com lets you generate multiple tokens, so you can implement token-per-service or token-per-developer patterns. If a token gets compromised, you can revoke it without disrupting other services.

One gotcha worth knowing: two-factor authentication on your name.com account blocks API access. If you need 2FA for security compliance, create a dedicated API-only account with restricted permissions.

Understanding API Constraints

The name.com API has a rate limit of 3,000 requests per hour. For most automation tasks, this is plenty. Updating records for a dozen domains or running scheduled zone backups fits comfortably within it.

Problems can show up during bulk operations. If you're migrating hundreds of records or running parallel updates across multiple environments, you'll start hitting 429 Too Many Requests responses. The solution is exponential backoff:

import time
import requests

def make_request_with_backoff(url, headers, method='GET', data=None, max_retries=5):
    """
    Makes an API request with exponential backoff on rate limit errors.

    Args:
        url: API endpoint URL
        headers: Request headers including auth
        method: HTTP method (GET, POST, PUT, DELETE)
        data: JSON payload for POST/PUT requests
        max_retries: Maximum number of retry attempts

    Returns:
        Response object or None if all retries failed
    """
    for attempt in range(max_retries):
        if method == 'GET':
            response = requests.get(url, headers=headers)
        elif method == 'POST':
            response = requests.post(url, headers=headers, json=data)
        elif method == 'PUT':
            response = requests.put(url, headers=headers, json=data)
        elif method == 'DELETE':
            response = requests.delete(url, headers=headers)

        if response.status_code == 429:
            wait_time = 2 ** attempt
            print(f"Rate limited. Waiting {wait_time} seconds before retry {attempt + 1}/{max_retries}")
            time.sleep(wait_time)
            continue

        return response

    print(f"Failed after {max_retries} attempts")
    return None

Beyond rate limits, you'll also encounter standard HTTP status codes. 401 Unauthorized means your credentials are wrong, so check your username, token, and base64 encoding. 403 Forbidden usually means you're missing the Content-Type: application/json header on POST or PUT requests. 404 Not Found means the domain or record doesn't exist. In sandbox environments, you need to register domains before you can manage their DNS.

Retrieving Data and Handling Pagination

The name.com API doesn't have a "Download Zone File" button. You reconstruct the zone view programmatically by fetching all records through the List Records endpoint.

The catch is pagination. Large zones with hundreds of records don't return in a single response. The API uses page and perPage parameters, with a default of 1,000 records per page. That handles most domains, but for larger zones or when you want smaller batches, adjust perPage accordingly.

Here's the logic for reconstructing a complete zone:

import requests
import json

def get_all_dns_records(domain, headers):
    """
    Retrieves all DNS records for a domain by handling pagination.

    Args:
        domain: Domain name (e.g., 'draftexample.work')
        headers: Request headers with authentication

    Returns:
        List of all DNS records for the domain
    """
    base_url = "https://api.name.com/core/v1"
    all_records = []
    page = 1
    per_page = 1000

    while True:
        url = f"{base_url}/domains/{domain}/records?page={page}&perPage={per_page}"
        response = requests.get(url, headers=headers)

        if response.status_code != 200:
            print(f"Error fetching records: {response.status_code}")
            print(response.text)
            break

        data = response.json()
        records = data.get('records', [])

        if not records:
            break

        all_records.extend(records)

        if len(records) < per_page:
            break

        page += 1
        print(f"Fetched page {page-1}: {len(records)} records")

    print(f"Total records retrieved: {len(all_records)}")
    return all_records

# Example usage
domain = "draftexample.work"
records = get_all_dns_records(domain, headers)

# Save to local "zone state" for analysis
with open(f"{domain}_zone_backup.json", 'w') as f:
    json.dump(records, f, indent=2)

Each record includes an id field. That's your handle for updates and deletions. The response structure looks like this:

[
  {
    "id": 12345,
    "domainName": "draftexample.work",
    "host": "test",
    "fqdn": "test.draftexample.work",
    "type": "A",
    "answer": "127.0.0.1",
    "ttl": 300
  }
]

Store these IDs when building automation. A common pattern is maintaining a local state file that maps logical names, like "production-web-server," to record IDs. This lets you update records by intent rather than hunting through API responses every time.

Managing State with CRUD Operations

DNS automation comes down to four operations: creating records, reading records (covered above), updating records, and deleting records.

Creating Records

The POST /core/v1/domains/{domain}/records endpoint creates new records. You provide the record type, hostname, and answer. The API validates record-type-specific rules:

def create_dns_record(domain, record_type, host, answer, ttl=300, headers=None):
    """
    Creates a new DNS record.

    Args:
        domain: Domain name
        record_type: Type of record (A, CNAME, TXT, MX, etc.)
        host: Hostname (use '' for apex domain)
        answer: Record value (IP for A, hostname for CNAME, etc.)
        ttl: Time to live in seconds (minimum 300)
        headers: Request headers with authentication

    Returns:
        Created record data or None on failure
    """
    url = f"https://api.name.com/core/v1/domains/{domain}/records"

    payload = {
        "host": host,
        "type": record_type,
        "answer": answer,
        "ttl": ttl
    }

    if record_type == "MX":
        payload["priority"] = 10

    response = requests.post(url, headers=headers, json=payload)

    if response.status_code == 200:
        record = response.json()
        print(f"Created {record_type} record: {host}.{domain} -> {answer}")
        return record
    else:
        print(f"Failed to create record: {response.status_code}")
        print(response.text)
        return None

# Example: Create an A record for a staging environment
create_dns_record(
    domain="draftexample.work",
    record_type="A",
    host="staging",
    answer="192.168.2.50",
    ttl=300,
    headers=headers
)

Validation matters here. An A record needs a valid IPv4 address. CNAME records can't coexist with other record types at the same hostname. TXT records need proper quoting for spaces. The API returns 400 Bad Request with details when validation fails.

You can verify the record was created in your name.com dashboard:

Updating Records

Updates use PUT /core/v1/domains/{domain}/records/{record_id}. You need the record ID from a previous GET request:

def update_dns_record(domain, record_id, record_type, host, answer, ttl=300, headers=None):
    """
    Updates an existing DNS record.

    Args:
        domain: Domain name
        record_id: ID of the record to update
        record_type: Type of record
        host: Hostname
        answer: New record value
        ttl: Time to live in seconds
        headers: Request headers with authentication

    Returns:
        Updated record data or None on failure
    """
    url = f"https://api.name.com/core/v1/domains/{domain}/records/{record_id}"

    payload = {
        "host": host,
        "type": record_type,
        "answer": answer,
        "ttl": ttl
    }

    response = requests.put(url, headers=headers, json=payload)

    if response.status_code == 200:
        print(f"Updated record {record_id}: {host}.{domain} -> {answer}")
        return response.json()
    else:
        print(f"Failed to update record: {response.status_code}")
        print(response.text)
        return None

# Example: Update production IP after server migration
update_dns_record(
    domain="draftexample.work",
    record_id=123456,
    record_type="A",
    host="staging",
    answer="192.168.2.100",  # New IP
    ttl=300,
    headers=headers
)

Updates are atomic at the record level. The API replaces the entire record, not individual fields. This prevents partial updates that could create invalid states.

Once you've run update_dns_record, the change shows up in the name.com dashboard:

Deleting Records

Deletion uses DELETE /core/v1/domains/{domain}/records/{record_id}. It's worth adding safety checks to prevent accidental deletion of critical infrastructure:

def delete_dns_record(domain, record_id, headers, require_confirmation=True):
    """
    Deletes a DNS record with safety checks.

    Args:
        domain: Domain name
        record_id: ID of the record to delete
        headers: Request headers with authentication
        require_confirmation: If True, requires explicit confirmation

    Returns:
        True if successful, False otherwise
    """
    url = f"https://api.name.com/core/v1/domains/{domain}/records/{record_id}"
    response = requests.get(url, headers=headers)

    if response.status_code == 200:
        record = response.json()
        print(f"About to delete: {record['type']} {record['fqdn']} -> {record['answer']}")

        critical_hosts = ['', 'www', 'mail', 'mx']
        if record['host'] in critical_hosts and require_confirmation:
            confirm = input("This is a critical record. Type 'DELETE' to confirm: ")
            if confirm != 'DELETE':
                print("Deletion cancelled")
                return False

    response = requests.delete(url, headers=headers)

    if response.status_code == 204:
        print(f"Deleted record {record_id}")
        return True
    else:
        print(f"Failed to delete record: {response.status_code}")
        print(response.text)
        return False

# Example: Clean up old staging environment
delete_dns_record(
    domain="draftexample.work",
    record_id=123456,
    headers=headers,
    require_confirmation=False  # Automated cleanup
)

For bulk deletions, track which records were successfully deleted. If the operation fails partway through, you can resume without duplicating deletions.

A Strategic Use Case: Ephemeral Environments

DNS automation unlocks workflows that simply aren't practical with manual management. Ephemeral environments are a good example.

There are times when you spin up a full environment, like dev or staging, using CI/CD pipelines. DNS entries are usually a part of that setup that you end up doing by hand. With the name.com API, you can automate that step entirely.

Feature branch deployments create temporary infrastructure, and each pull request can get its own subdomain:

def create_ephemeral_environment(domain, branch_name, server_ip, headers):
    """
    Creates DNS records for a temporary feature branch environment.

    Args:
        domain: Base domain
        branch_name: Git branch name (sanitized for DNS)
        server_ip: IP address of the ephemeral server
        headers: Request headers with authentication

    Returns:
        Created record or None
    """
    safe_branch = branch_name.lower().replace('_', '-').replace('/', '-')
    host = f"feature-{safe_branch}"

    return create_dns_record(
        domain=domain,
        record_type="A",
        host=host,
        answer=server_ip,
        ttl=300,  # Short TTL for quick cleanup
        headers=headers
    )

# In your CI/CD pipeline
branch = os.getenv('GITHUB_BRANCH')  # e.g., 'user-auth-refactor'
server_ip = provision_server()  # Your infrastructure provisioning

record = create_ephemeral_environment(
    domain="draftexample.work",
    branch_name=branch,
    server_ip=server_ip,
    headers=headers
)

print(f"Environment available at: https://feature-{branch}.example.com")

Keep in mind that the provision_server function (or similar function) is normally run on your CI/CD infrastructure and should already be in place for this code to work.

If that runs successfully from your CI/CD environment, you'll end up with a record that looks like this:

Why Developers Feel Unproductive Even When They're Shipping

Jakkie Koekemoer — Wed, 04 Mar 2026 16:58:36 +0000

I've talked to a lot of engineering managers who can't figure out why their developers seem frustrated. The sprint metrics look fine. PRs are getting merged. Tickets are moving. But morale is low, and the team keeps saying they feel like they're not getting anything done.

After digging into it, I've found the problem is almost never about output. It's about the conditions under which that output gets produced.

Most developers aren't struggling because they're lazy or distracted. They're struggling because their calendars make sustained focus structurally impossible. You can ship code in 20-minute windows between meetings all day long and still end the day feeling like you accomplished nothing, because the kind of work that actually feels meaningful requires more than 20 minutes to do.

There's a name for this: productivity dysmorphia. It's the gap between what you objectively produced and what you subjectively feel like you produced. And the research explains exactly why that gap exists.

Why Fragmented Days Feel Empty

When you switch tasks, your brain doesn't just pick up where it left off. A study from UC Irvine found it takes an average of 23 minutes to fully regain focus after an interruption. That's not 23 seconds. It's 23 minutes of recovery time before you're thinking at the depth you were before.

That number becomes a real problem when you look at how most engineering calendars are structured. If you have meetings at 9:30, 11:00, 1:00, and 3:00, you don't have four gaps of free time. You have four windows that are almost entirely consumed by context-switching overhead. By the time your brain is ready to do something hard, the next meeting is already close enough to pull your attention toward it.

A 30-minute gap between meetings yields about 7 minutes of usable focus. A 2-hour block yields nearly 100. The difference isn't linear; it's structural.

Psychologist Sophie Leroy's research on attention residue makes this worse. Even after you physically move to a new task, part of your cognitive bandwidth stays stuck on the previous one. You leave a 2 PM standup and open your editor, but your brain is still processing what was said in the meeting. You're typing, but you're not thinking.

This is why three hotfix PRs feel less satisfying than one complex feature, even if the hotfixes took longer in total. The hotfixes get done in short bursts of reactive work. The complex feature requires the kind of deep, sustained focus that Csikszentmihalyi called Flow: full immersion in a hard problem, where time disappears and progress feels real. A fragmented calendar makes Flow nearly impossible to reach. So developers ship things and still feel empty, because they never got to do the work that actually satisfies them.

Paul Graham described the structural version of this problem as the maker's schedule versus the manager's schedule. Managers think in one-hour blocks, so a single meeting just fills a slot. For a developer, the same meeting can ruin an entire afternoon by eliminating any realistic chance of reaching deep focus before or after it.

The Problem With Introspection

Here's what makes productivity dysmorphia hard to diagnose: asking yourself how your day went doesn't work.

Ask a developer at 5 PM how many real focus blocks they had that day. They'll probably say "a few." The actual number, meaning uninterrupted stretches long enough to load context and do hard work, is often zero. Research on retrospective time perception shows that we consistently compress the memory of fragmented work and expand the memory of focused work. What felt like a productive day was actually dozens of short reactive tasks stitched together. The brain smooths it over. The fatigue is real, but the memory lies.

This is where data becomes genuinely useful, not as a productivity metric, but as a reality check.

GitHub's Good Day Project studied 40 developers over two weeks and found that with minimal interruptions, developers had an 82% chance of having a good day. When interruptions dominated their day, that dropped to 7%. They also found that the developers who shipped the most pull requests didn't necessarily have the best days, because being constantly pulled out of focus to handle PRs appeared to cancel out the satisfaction of completing them.

Source: GitHub Octoverse Good Day Project, 2021. N=40 developers over two weeks.

That last finding is the clearest illustration of productivity dysmorphia I've seen in the research. You can be shipping constantly and still feel like you're not getting anywhere.

Span addresses this at the team level. It connects to your codebase and engineering toolchain and automatically categorizes where developer time is actually going across meetings, deep work, maintenance, and context switching, without requiring manual tracking. When an engineering manager can see that their team logged 200 hours last week but the majority was consumed by meetings and reactive work, the conversation changes. The problem stops being "we need to work harder" and starts being "we need to protect more time for actual engineering work."

That shift in framing matters. When a team attributes the hollow feeling to personal failure, it's demoralizing and hard to fix. When they can see it in a dashboard and attribute it to a structural problem, it becomes something they can actually address.

What to Do About It

None of the fixes here are complicated. The hard part is treating them as real constraints rather than nice-to-haves.

Protect at least one two-hour block per developer per day. This is the minimum viable unit of deep work. Thirty or forty-five minutes isn't enough to load context on a hard problem and make meaningful progress. By the time a developer has pulled the branch, reviewed the ticket, traced the relevant code, and formed a clear mental model of what needs to happen, the window is already closing. If you look at your team's calendars and there's no consistent uninterrupted two-hour stretch, you've scheduled a week of reactive work and called it an engineering sprint.

Batch reactive work into fixed windows. Code reviews, Slack replies, and PR comments are real work, but they're interruptive by nature. Grouping them into two fixed windows per day, say mid-morning and late afternoon, keeps them from bleeding into focus time throughout the day. This is a scheduling convention, not a policy. It requires no tools and no approval.

Establish explicit response-time expectations for Slack. The biggest source of interruptions for most engineering teams isn't meetings. It's the assumption that Slack messages need a near-immediate reply. That assumption is almost never written down anywhere, but it shapes behavior constantly. Teams that set a clear norm, like "non-urgent messages get a response within two hours," consistently report less anxiety without any measurable drop in communication quality. One team conversation can change the default permanently.

Use data to make the problem visible to leadership. Individual developers can protect their own calendars to some extent, but the real leverage is at the team and org level. When a manager can show in a dashboard that 60% of engineering time is going to meetings and reactive work, it's a different conversation than asking people to "block more focus time." Span's engineering time categorization is useful here because it provides the kind of objective, code-linked data that's hard to argue with.

That said, none of these changes require a reorganization or executive buy-in to start. They require that someone on the team decides to treat focus time as a resource worth defending rather than the default thing that gets scheduled over.

Final Thoughts

Productivity dysmorphia is a predictable outcome of how most engineering orgs are structured, not a sign that developers aren't working hard enough. When the calendar makes deep work structurally impossible, people feel unproductive because they are, not in terms of output, but in terms of the work that actually registers as meaningful.

The fix isn't motivational. It's architectural. Protect the blocks, batch the reactive work, and make the time distribution visible with data. The developers on your team probably already know something is wrong. The data just gives you a way to show it to everyone else.

Want to understand where your engineering team's time is actually going? Span gives engineering leaders an automated view of how developer time is distributed across deep work, meetings, and reactive tasks, without the manual overhead.

AI is Killing the "Junior" Role. Here is How We Save It.

Jakkie Koekemoer — Wed, 25 Feb 2026 13:11:52 +0000

The desk next to yours is empty. It used to belong to a junior developer. It's not coming back.

Introduction: The Empty Desk Next to You

Look at your company's open engineering reqs. Chances are, you're hiring for Senior, Staff, or Principal engineers. The junior reqs? Frozen. Or quietly removed.

This isn't anecdotal. Stanford's Digital Economy Lab found that employment for the youngest software developers dropped 13% below its late-2022 peak by mid-2025, while older developers in the same fields remained stable. A Harvard study analyzing 62 million workers across 285,000 firms found that following GenAI adoption, junior employment declined sharply in adopting firms relative to non-adopters, while senior employment remained largely unchanged, driven by slower hiring rather than increased separations or promotions. SignalFire's 2025 State of Tech Talent Report found that new graduate hiring at major tech firms has fallen over 50% since 2019.

The economic logic is straightforward. Why pay a junior engineer \$80K to write boilerplate when Claude Code does it for \$20 per month? The math is brutal, the incentive is real, and companies are acting on it.

But this creates a problem that doesn't show up on any quarterly earnings call: we are eating our seed corn. If today's juniors don't get the reps, there will be nobody to become the seniors who clean up AI's mess in 2030. AWS CEO Matt Garman put it bluntly when he called the trend of cutting junior hiring "one of the dumbest things I've ever heard", asking: "How's that going to work when ten years in the future you have no one that has learned anything?"

That's the question this article is trying to answer.

The Death of "Wax On, Wax Off"

The Dreyfus Model of Skill Acquisition describes five stages of competence: Novice, Advanced Beginner, Competent, Proficient, Expert. The critical insight is that you can't skip stages. You progress by doing, failing, and building pattern recognition through repetition. In the Karate Kid, Mr. Miyagi doesn't explain the philosophy of karate on day one. He has Daniel wax a car, sand a floor, and paint a fence. The muscle memory comes first. The understanding follows.

Mr. Miyagi's "wax on, wax off" method is the original onboarding framework: repetitive, concrete tasks that build muscle memory before the deeper principles are ever explained.

Juniors used to learn the same way. They wrote the unit tests. They built the CRUD endpoints. They handled the CSS tickets that nobody else wanted. The work was boring. That was the point. In doing repetitive, well-scoped tasks, they built the mental model of how a codebase holds together. They learned to read error messages. They developed the intuition for where bugs hide.

AI has automated the gym.

The Missing Rung: AI has automated the entry-level tasks that juniors used to use as their training ground, leaving a gap that's impossible to jump.

The bottom rungs of the career ladder, the boilerplate code, the unit tests, the CRUD endpoints, have been removed. And we're now telling juniors to jump straight to the top.

The result is what you might call the Hollow Senior: a developer with five years of "experience" that is really five years of prompting AI, accepting outputs, and shipping features without ever debugging a race condition, optimizing a slow query, or understanding why a seemingly simple database index choice can bring down a production system at scale. They have the title. They lack the intuition.

The research backs this up. Aalto University researchers studied a firm where automation dependence eroded core skills so thoroughly that when the system was removed, employees could no longer perform basic tasks. A Microsoft and Carnegie Mellon study found that higher AI confidence directly correlated with reduced critical thinking. And a METR randomized controlled trial found that experienced developers using Cursor completed real-world tasks 19% slower with AI than without, while still believing the tools would save them around 24% of their time.

The perception-reality gap is the most dangerous part. Developers, and by extension their managers, are systematically overestimating how much they're learning and growing.

The Problem with "Volume" Metrics

Here's where the measurement problem compounds everything.

If you evaluate a junior engineer on lines of code, tickets closed, or PR velocity, you've just handed them the wrong objective function. Goodhart's Law states that when a measure becomes a target, it ceases to be a good measure. In software engineering, it's always been a problem. Under AI, it becomes catastrophic.

A junior developer measured on ticket velocity has a clear path to success: accept the first thing Cursor outputs, open a PR, move to the next ticket. The metric goes up. The learning doesn't. They're not a developer anymore. They're a human proxy for an LLM, and GitClear's analysis of 211 million changed lines of code shows exactly what this looks like in a codebase: refactoring activity dropped from 25% of changed lines in 2021 to under 10% by 2024. Copy-pasted code increased nearly 50%, from 8.3% to 12.3% of changed lines.

Martin Fowler has argued for decades that "copy and paste programming leads to high lines of code counts and poor design." AI-assisted development has automated copy-paste at scale. The metrics look great. The codebase quietly degrades.

And teams reinforce this. If your sprint retros celebrate ticket throughput and your 1:1s ask "what did you ship this week?", you're training your juniors to optimize for output over understanding. It's Goodhart's Law on steroids, because AI gives juniors the ability to hit the metric convincingly without doing the underlying work.

Kent Beck's model frames this as Effort, Output, Outcome, Impact. The mistake is measuring juniors on Output when what actually matters for their development is the quality of the Effort. Are they building understanding? Are they encountering and overcoming resistance? Or are they just turning prompts into PRs?

The Solution: Optimize for "Learning Velocity"

We need to change the definition of a junior's job from "shipping code" to "acquiring context."

That sounds idealistic until you think about what a junior is actually worth to your organization. The value is not their output today. It's their judgment in three years. Every task they genuinely understand, every bug they trace to its root cause, every architectural tradeoff they see play out in production, that's the compounding asset you're building. AI can inflate short-term output. It cannot shortcut the accumulation of engineering intuition.

This is where Span offers a genuinely different lens. Rather than counting commits or tickets, Span tracks ramp-up patterns at the developer level, giving engineering managers visibility into whether a junior is actually growing in scope and independence, or whether they're stuck in a loop of simple tasks regardless of how many PRs they're opening.

The key metric is Onboarding Velocity: tracking not just whether a junior merged their first PR, but how long it takes to reach their 10th, their 20th, and what the complexity profile of those PRs looks like over time. A junior who hits their 10th PR in week two by mass-prompting Cursor is not on the same trajectory as one who hits it in week six by working through progressively harder problems with genuine comprehension.

The detail Span surfaces is the rate of growth: is a junior's scope expanding over time, or are they still doing the same class of task at month four that they were doing at month one? That distinction is invisible to any tool that only counts activity. It's the difference between a junior who is on track to become a strong mid-level engineer and one who will be a permanent prompt-relay.

Practical Mentorship for the AI Era

Reframing the metric is necessary but not sufficient. You also have to change what you ask juniors to do, and how you structure your involvement.

Three practices that actually work:

1. The "No-AI" Sandbox. Assign specific tasks where AI assistance is off-limits. These don't have to be large. In fact, they shouldn't be. The point is forcing a junior to build a mental model before reaching for a shortcut. Debug this failing test without any external help. Trace this API call from the controller to the database by reading the code. The discomfort is the mechanism. You're not punishing them; you're creating the conditions for the muscle memory that AI use requires but cannot build on its own.

2. Reverse Code Review. Have your junior review the AI's output, or yours. Ask them to explain every line they didn't write. If they can't, that's diagnostic information, not a performance failure. It tells you where the gaps are and where to focus mentorship. The Engineering Enablement approach suggests requiring juniors to annotate AI-generated code in PRs with explicit notes on what they verified, what they changed, and why they trusted or rejected sections of the output. This turns passive AI use into an active comprehension exercise.

3. Measure "Review Depth." Span's PR review tracking lets you see whether a junior is leaving substantive comments on other people's code or just approving ("LGTM"). A developer who asks meaningful questions in review, who catches edge cases, who pushes back on naming or architectural choices, is building the judgment that will compound. A developer who rubber-stamps everything is not. These signals are invisible without deliberate measurement.

The broader reframe here is that mentorship in the AI era is less about showing juniors how to write code and more about teaching them how to interrogate it. The hard skills shift: reading and evaluating code becomes more important than writing it from scratch. System-level reasoning, the ability to ask "what happens to this service when that one fails?", becomes more valuable, not less, because AI tools are poor at it. Addy Osmani describes senior engineers increasingly serving as "AI code reviewers," which means the skill of critical evaluation is now both the most important skill a junior can develop and the one most at risk of atrophy.

This takes explicit investment. As Wanderson Lacerda argues, training juniors is no longer a byproduct of getting work done. It's a capital expense. You have to budget for it, structure it, and measure it, or it won't happen.

Conclusion

The short-term math on cutting junior hiring is correct. AI is cheaper than a new grad for boilerplate. But the five-year math runs the other way. The systems AI is generating today will need human engineers to maintain, extend, and fix. The Google DORA 2024 Report found that for every 25% increase in AI adoption, delivery stability decreased 7.2%. Somebody has to own that stability. That somebody needs deep engineering judgment. That judgment takes years to build, and you can't build it if you stop hiring the people who need to develop it.

Mentorship is no longer a nice-to-have program on the culture page of your handbook. It's a survival strategy for the industry. Protect the junior role, not out of charity, but because your senior pipeline in 2030 depends entirely on the juniors you invest in today.

The teams that figure this out, that measure learning velocity instead of ticket count, that create deliberate space for skill formation alongside AI use, are the ones who will have senior engineers with real judgment when the rest of the industry is trying to figure out why their AI-generated codebase is on fire and nobody knows why.

Are you worried about the next generation of engineers? Share your best strategy for mentoring in the age of AI in the comments below.

"LGTM": Are We Reviewing Code or Just Rubber Stamping It?

Jakkie Koekemoer — Thu, 19 Feb 2026 10:41:51 +0000

You open a 1,200-line PR at 9 AM. The CI is green. You scroll for four minutes, click "Approve," type "LGTM," and move to the next one.

You didn't review it. You logged it.

AI coding assistants generate modules in seconds. But reading code happens at human speed. This asymmetry creates a bottleneck: code influx permanently exceeds verification capacity. We're not reviewing anymore. We're performing security theater in the PR queue.

The Tech Debt Singularity

The Tech Debt Singularity is when incoming code rate exceeds review rate forever. Not a temporary backlog. A structural break.

LLMs don't get bored writing 50 similar functions. They don't care if the PR is 2,000 lines. Humans do. We skim. We trust the tests. We hope.

The result: code that works in isolation but fights itself architecturally. Six months later, you add a feature and realize the codebase is incoherent. One module uses factories. Another uses dependency injection. A third hard-codes everything. Each decision was locally correct. Together, they're a maze.

Research shows bugs caught in review cost exponentially less than bugs in production. But only if you actually review the code.

Three Symptoms You're Rubber Stamping

1. The Nitpick Review

600-line PR. Dense logic with state management, async flows, error handling. Understanding it takes 30 minutes. You have 10.

You rename userData to userProfile. Point out a missing space. Flag a linting error CI already caught. Three thoughtful-looking comments. Click "Approve."

You reviewed syntax. Not logic.

2. Time-to-Approve Collapse

1,200 lines approved in four minutes. Even scanning at 300 lines per minute, you can't verify logic, edge cases, or abstraction quality. You can scroll. You can spot-check. You can't review.

Google's research confirms: meaningful reviews take time. When approval time drops while PR size stays constant, you're not reviewing faster. You're reviewing less.

3. Blind Trust in AI

"Generated by o1, so the logic is sound." Wrong.

AI assistants generate plausible code. They don't understand your business logic. Your payment service has a race condition when webhooks arrive simultaneously. Your database uses soft-deletes that need special handling. The LLM doesn't know. It generates code that looks right but breaks in context.

Research backs this up. CodeRabbit's analysis of 470 open-source PRs found AI-generated code contained 1.7x more issues overall than human-written code. Logic and correctness issues were 75% more common. Error handling gaps appeared at nearly 2x the rate. Security vulnerabilities, particularly XSS, showed up at 2.74x higher rates.

The fundamental problem: 66% of developers cite "AI solutions that are almost right, but not quite" as their biggest frustration with AI tools. Teams at Span have been measuring this effect across millions of lines of code. Their data shows that AI-generated code creates specific patterns of defects that require different verification strategies than human-written code.

Without careful review, you catch these issues in production.

The Review Quality Framework

You need metrics that show when you're cutting corners. Most engineering metrics tools track PR velocity or cycle time. Metrics that reward speed. But speed isn't safety.

What matters is review quality. Three metrics expose rubber stamping:

1. Review Burden Ratio

Lines changed and complexity vs. time spent reviewing. When large, complex PRs get approved in minutes, your ratio collapses. This is your smoke detector.

2. Review Coverage

Percentage of lines actually viewed, not just scrolled past. Under 80% coverage means skimming. GitHub and GitLab track this in their APIs, but most teams never look at it.

3. Time to Substantive Feedback

How long before real feedback, not linting nitpicks. If first comments are always "rename this variable" or "fix spacing," you're reviewing cosmetics while skipping logic.

When teams track these metrics, patterns emerge. One team found their velocity was up 40% but review depth down 60%. They were shipping bugs faster.

The challenge: most teams don't track this systematically. It requires correlating PR metadata with actual reviewer activity, understanding code complexity, and distinguishing substantive review from rubber stamping. This is particularly critical now that AI-generated code is flooding PRs. Span's research shows this code requires different verification strategies, making review depth metrics even more important.

Five Strategies to Stop Rubber Stamping

1. Enforce 400-Line PR Limits

SmartBear's study with Cisco found review effectiveness drops sharply after 400 lines. Beyond that, reviewers skim.

Set a hard limit: 400 lines maximum. Larger changes need multiple PRs with clear dependencies. This slows shipping. That's the point. You're choosing correctness over speed.

AI makes this easier. Ask Claude or ChatGPT to split a 1,200-line refactor into three atomic PRs. It takes seconds.

2. Use AI-Generated PR Summaries

Have AI compress the PR into a summary before review:

What changed and why
High-level architecture decisions
Edge cases considered
Tests added

The summary doesn't replace review. It gives you context so you can focus on logic instead of parsing syntax. Read the summary first, then review the code.

3. Surface Declining Review Quality to Management

When Review Burden Ratio trends down, show management the data. "We can't review this volume safely. We need to slow shipping or add reviewers."

This feels like admitting failure. But the alternative is shipping unreviewed code and catching bugs in production. Multiple studies show code review catches the majority of defects before release. Rubber stamping defers those bugs.

Treat reviewer capacity as a hard constraint. If you won't deploy without tests, don't deploy without real reviews.

4. Rotate Review Responsibilities

Don't bottleneck all reviews through one senior engineer. Rotate across the team. This distributes effort and reduces the temptation to rubber stamp when overwhelmed.

Junior engineers improve at reviewing through practice. Senior engineers get breathing room.

5. Make "I Don't Have Time" Acceptable

Create a culture where "I can't review this properly right now" is acceptable. This beats rushed approval.

If reviewers consistently lack time, that's data. The team is under-resourced for the code volume being generated. Use that signal to adjust expectations or add capacity.

The Decision Framework: When Is a Review Good Enough?

Use this three-question framework before approving:

1. Can I explain the core logic to someone else?

If you can't summarize what the code does and why, you didn't review it. You scanned it.

2. Have I considered failure modes?

What breaks if the network times out? What happens with malformed input? If you haven't thought about edge cases, you didn't review.

This is particularly important for AI-generated code. Span's analysis shows AI code contains significantly more error handling gaps and edge case issues than human code. You need to actively verify these patterns, not assume they're handled.

3. Does this fit our architecture?

Does this match existing patterns? If it introduces a new approach, is that justified? Inconsistent patterns compound into technical debt.

If you answer "no" to any question, don't approve. Request time or ask for the PR to be split.

What Rubber Stamping Actually Costs

Rubber stamping erodes architecture gradually. When nobody reads code holistically, each PR optimizes locally. Together, they create global incoherence.

Example: You approve three PRs in one day. One uses factories. Another uses dependency injection. A third hard-codes dependencies. None are wrong individually. Together, they create inconsistency.

Six months later, new engineers spend weeks learning idiosyncrasies. Features take longer because every change navigates conflicting patterns. This is how brownfield codebases form. Not from malice. From inattention compounded over time.

AI accelerates this. It generates more code faster than humans can, magnifying the cost of each unreviewed decision. And the data shows AI code creates specific architectural challenges. GitClear's analysis of 153 million changed lines of code found code churn doubled and copy/pasted code increased significantly, with AI-generated code resembling "an itinerant contributor, prone to violate the DRY-ness of the repos visited."

The teams who understand this best are those measuring it. Span's platform detects AI-generated code at the chunk level, letting teams see exactly where these patterns appear and correlate them with code quality outcomes. This visibility matters because you can't fix what you can't measure.

Implementation Checklist

This week:

Set a 400-line PR size limit in your repo settings
Add a PR template that requires a summary section
Start tracking Review Burden Ratio manually (spreadsheet with PR size, review time, approval)

This month:

Review your team's average time-to-approve vs. PR size
Identify PRs approved in under 5 minutes that exceeded 500 lines
Present findings to your team

This quarter:

Implement automated review quality tracking
Rotate review responsibilities weekly
Measure defect rates before and after implementing limits

Conclusion

Code review is the last defense against chaos. When you rubber stamp, you're crossing your fingers and hoping tests are comprehensive.

The temptation to skim is constant. You're busy. The PR looks fine. CI is green. But "looks fine" isn't "is fine." This is especially true now that AI code makes up a growing percentage of PRs. Code that looks correct but contains subtle defects requires thorough verification.

Set limits. Track data. When Review Burden Ratio drops, treat it as a signal to slow down or add capacity.

AI code generation is fast. But speed without verification is just technical debt accumulating faster than you can pay it off. The hard part isn't generating code. The hard part is understanding it.

That part is still on you.

Be honest: Have you approved a PR this week that you didn't actually read? Tell us your "Rubber Stamp" horror stories in the comments.

Copilot vs. Cursor vs. Reality: Why 59% of Developers Use Both (And Then Some)

Jakkie Koekemoer — Fri, 13 Feb 2026 12:48:00 +0000

Here's the open secret on your engineering floor: your company pays for GitHub Copilot Enterprise, but you've been sneaking Cursor sessions since December. Your tech lead pretends not to notice because she's running Claude Code in her terminal for the gnarly refactors. The intern, bless him, still thinks we all follow the "approved tooling" memo.

We don't. According to Microsoft's own research, 78% of AI users now bring their own tools to work, and a Gartner survey found 69% of organizations either know or suspect their developers are using prohibited AI tools. This isn't shadow IT in the malicious sense. It's an efficiency signal. Developers aren't sneaking tools to cause problems. They're sneaking tools because the sanctioned ones can't keep up.

The "One Tool to Rule Them All" procurement strategy made sense in 2022. In 2026, it's actively killing velocity.

We fragmented because one tool can't serve three cognitive modes

The AI coding landscape splintered for a reason. The tools that won aren't competing for the same job. They're serving fundamentally different cognitive functions.

The "Safe" choice is Copilot. GitHub reports 90% of Fortune 100 companies now use it, and its enterprise features, SSO, audit logs, compliance certifications, make procurement teams happy. It generates 46% of all code written by its users, up from 27% at launch. For inline autocomplete in familiar patterns, it works fine. But for power users, Copilot increasingly feels like a reliable sedan when you need a rally car. The \$39/seat/month Enterprise tier buys you safety features, not horsepower.

The "Flow" choice is Cursor. Cursor crossed 1 million daily active users by December 2025 and hit a \$29 billion valuation by November. It's a VS Code fork rebuilt around AI-first workflows, not an extension bolted on afterward. The difference matters. Cursor owns your entire context window. Its Composer mode can coordinate multi-file edits from a single prompt. Its Tab completion has sub-400ms latency because they acquired Supermaven specifically for speed.

The "Agent" choice is Claude Code. Anthropic's terminal-native tool hit \$1 billion ARR in just six months, making it one of the fastest-growing enterprise products ever. Claude Code doesn't live in your IDE. It lives in your terminal, executes commands, creates pull requests, and handles 90%+ of git interactions for developers who use it heavily. For complex refactors, multi-step autonomous tasks, and codebase exploration, it's a different beast entirely.

Here's what senior developers figured out: these tools serve three distinct cognitive modes. Flow is the tab-tab autocomplete while you're typing, keeping you in the zone. Reasoning is the chat interface when you're stuck, rubber-ducking a problem. Autonomy is offloading entire tasks to an agent while you work on something else. Copilot dominates the middle. Cursor owns Flow. Claude Code wins Autonomy. Asking which is "best" misses the point. They're not interchangeable.

The JetBrains 2025 survey confirms this fragmentation: GitHub Copilot sits at 30% usage and ChatGPT at 41% among developers who use AI tools regularly. According to Second Talent, 59% of developers now run three or more AI coding tools in parallel. This isn't chaos, it's optimization. Developers pick tools based on task requirements. Even internally at Draft.dev, we use different models based on their strengths. Smart teams use the right tool for the job.

The friction of "approved tooling" burns money and momentum

When your approved IDE and your preferred AI tool don't match, you're switching contexts constantly. The mental overhead compounds throughout the day.

But here's the number that should scare procurement: 53% of enterprise software licenses go unused, according to Zylo's 2025 SaaS Management Index. Gartner calls this "shelfware" and estimates it represents 30% of typical SaaS spend. For the average enterprise, that's \$21 million annually in wasted licenses.

The pattern is everywhere. A 200-engineer company paying \$39/seat/month for Copilot Enterprise spends roughly \$94,000 a year. Usage dashboards often show maybe 40% of seats active. Half of those active users have Cursor Pro on their personal credit cards anyway. They're not getting Copilot Enterprise value. They're funding zombie licenses while developers self-fund the tools they actually need.

IT procures the "safe" choice to satisfy security and compliance. Developers trial it, find it doesn't match how they actually work, then quietly install what does. According to Zylo's 2026 SaaS Management Index, AI-native app adoption surged 108% year-over-year overall (393% for large enterprises), largely driven by expense-based purchasing outside formal procurement. The approved stack isn't designed around developer experience, it's designed around vendor relationships and audit checkboxes.

The data gap that makes these conversations impossible

Here's the core problem: every conversation about switching tools hits the same wall. "That's just your preference. We can't justify budget based on vibes."

This objection is completely reasonable. You can't walk into a budget meeting and say "Cursor feels faster." That doesn't survive a procurement committee. You need numbers. But AI tool telemetry is a mess. Each vendor reports different metrics, measured differently, with obvious incentives to look good. GitHub tells you Copilot acceptance rates. Cursor tells you completions. Neither tells you what actually shipped or whether the code stuck.

The missing piece is independent measurement. You need to see what's actually happening in your codebase, not what vendors claim in their dashboards. This is where platforms like Span come in.

Span is a developer intelligence platform, but the feature that changes the conversation is their AI Code Detector. It doesn't rely on vendor telemetry or IDE integrations. Instead, it uses a model called span-detect-1 to analyze code artifacts directly, classifying each chunk as AI-generated or human-written with 95% accuracy across Python, TypeScript, JavaScript, Ruby, and other languages.

Why does this matter? Because it works universally across all AI coding tools. Copilot, Cursor, Claude, ChatGPT copy-paste, it doesn't matter. Span sees what actually landed in your codebase. No self-reporting. No vendor dashboards. Just ground truth from code.

This kind of data changes the argument entirely. Instead of "I prefer Cursor," you can say: "Developers using Cursor have a 23% higher AI code ratio on feature branches and ship with 18% less rework in code review." That's a conversation procurement can act on. You're not asking them to trust anyone's intuition. You're showing them which tools actually correlate with output and quality.

Span also tracks investment mix, DORA metrics, and can correlate AI code ratios with defect rates over time. For leaders trying to justify AI budgets to executives, that's the missing link. Most companies can only measure utilization because that's what vendor dashboards show. Span lets you measure impact at the code level.

A proposal for 2026: the "BYOAI" stipend

Here's the pitch to engineering leadership everywhere: stop procuring AI coding tools like it's 2015.

We already treat hardware this way. Most companies gave up mandating specific laptops years ago. You get a budget, you pick your machine, IT ensures it meets security requirements. The same model works for AI tools.

Give developers a monthly AI stipend, maybe \$50-75, and let them pick their stack. Cursor Pro is \$20/month. Claude Pro is \$20/month. Copilot Pro is \$10/month. A developer could run all three for less than what you're paying for unused Enterprise seats. Some will stick with Copilot. Some will go all-in on Cursor. Some will mix depending on the task. That's the point.

"But what about security and compliance?" Fair question. The answer isn't locking down inputs. It's observing outputs. Tools like Span give you visibility into what's actually happening in your codebase without mandating specific tools. You can enforce policies at the code level, flagging AI-generated code for additional review, tracking quality metrics by tool, identifying which patterns correlate with defects, rather than trying to control which autocomplete a developer uses.

This flips the mental model. Instead of "approve tools, hope they get used," you "observe outcomes, fund what works." The developers who generate the highest-quality AI-assisted code with the fastest cycle times are probably using the tools that work best for their style. Learn from them instead of fighting them.

IBM's Cost of a Data Breach report found that organizations with high shadow AI had \$670,000 higher breach costs, primarily because of missing access controls and visibility. The solution isn't banning shadow AI, that's been failing for three years. The solution is bringing it into the light with proper observability while respecting developer autonomy.

The best tool is the one that gets used

Here's the uncomfortable truth: 84% of developers now use AI coding tools, but trust in AI output has dropped to 33%. Adoption is universal. Enthusiasm is not. Developers are pragmatists. They'll use what helps and abandon what doesn't, regardless of what's on the approved list.

If you're a manager reading this, stop fighting the shadow stack. The war is over, and the shadow stack won. Your job now is to measure it, fund it, and get out of the way. The companies that will win the next few years of engineering productivity aren't the ones with the tightest tool controls. They're the ones that figured out how to harness developer agency while maintaining visibility into what ships.

The "One Tool to Rule Them All" era is over. Welcome to the multi-tool reality. Your developers already live here.

We all have that one "unapproved" AI tool we can't live without. I'm curious, what's in your shadow stack right now? Let's argue about the best setup in the comments.

Why I Ignore DORA Metrics (And What I Track Instead)

Jakkie Koekemoer — Tue, 03 Feb 2026 09:52:00 +0000

Your deployment frequency is up 40%. Lead time for changes is down. The DORA dashboard is glowing green. Your manager is happy.

Then your best engineer quits. She tells you in the exit interview: "I spent more time in meetings than writing code."

You check the metrics again. They still look great. What did you miss?

DORA metrics measure velocity. They don't measure whether your developers have time to think. Your team can hit elite DORA scores while engineers burn out from constant context switching. The deployments keep flowing, right up until your senior people start leaving.

The dashboard says you're fast. The reality is you're fragmented.

The Science of Flow vs Velocity

Research from UC Irvine found that after an interruption, it takes an average of 23 minutes and 15 seconds to return to your original task. That's not a guess. That's controlled measurement of knowledge workers under observation.

Here's what that means: if you get interrupted twice during what you thought was an hour of coding time, you're getting about 14 minutes of real work done.

Flow state changes this equation entirely. When Mihaly Csikszentmihalyi spent 40 years studying optimal performance, he identified that flow requires uninterrupted concentration where challenge matches skill. You can't get there in 30-minute blocks between meetings.

DORA metrics can't see this difference. A deployment is a deployment, whether it took 30 minutes of focused work or 6 hours of context-switching hell.

The Real Problem: Fragmented Time

Clockwise analyzed 1.5 million meetings across 80,000 engineers. The average software engineer spends 10.9 hours per week in meetings. That sounds manageable until you see the next number: 6.3 hours per week in fragmented time.

Fragmented time is the 30-minute gap between standup and your 1:1. It's the 45 minutes between the architecture review and the sprint planning session. It's calendar space that looks empty but is functionally useless.

You can't write meaningful code in 30 minutes. You definitely can't debug a complex system issue. At best, you answer Slack messages and feel busy.

Here's what a fragmented calendar looks like:

This engineer had an 8-hour workday with only two meaningful blocks for deep work: 45 minutes before lunch and 90 minutes in the late afternoon. By the time you load your mental model of the codebase, half the block is gone.

GitHub's Good Day Project found that developers with minimal interruptions have an 82% chance of having a productive day. When interrupted most of the day, that drops to 7%.

Going from two to three meetings per day lowers your progress chances from 74% to 14%.

Yet DORA metrics would show this engineer as equally productive on both types of days, as long as they shipped commits.

How to Measure Flow

Stop trusting your gut. Your calendar data tells the real story.

Traditional engineering metrics only look at Git activity. They count commits, PRs, and deployments. They miss the calendar entirely.

I've been working with developer intelligence platforms like Span through the agency I'm working for, and I've seen how useful it is when you connect calendar data to code output. It shows you something most engineers have never seen: how much uninterrupted time you have.

This engineer thought they had 40 hours of work time. The data shows 20.5 hours of actual focus time, with 11.6 hours consumed by recurring meetings. The breakdown reveals where the time goes: 5.5 hours in 1:1s, 4.3 hours in small group meetings, and fragments in larger meetings.

The maps directly to what Paul Graham calls "Maker Hours" versus "Manager Hours". Makers need blocks of at least 2-4 hours. Managers can work in 30-minute increments. When you see your calendar data broken down this way, you can spot the mismatch: you're being paid to make things, but your schedule looks like a manager's.

Here's what the data typically reveals:

You thought you had 30 hours of coding time per week
Your calendar shows only 19.6 hours of focus time (2+ hour blocks)
After accounting for context switching, you get 12-14 hours of actual deep work

The insight isn't that you're slow. The insight is that the system is slow.

The fragmented time report becomes evidence. You're not making excuses. You're showing math.

How to Reclaim Your Calendar

Once you see the fragmentation, you can fix it. Here are three tactics that work:

Meeting Bankruptcy

Decline every recurring meeting that lacks a clear agenda. If the organizer can't articulate what decisions will be made or what information will be shared, it's a status update disguised as a meeting.

Status updates belong in async channels, not on your calendar.

Clustering

Move all meetings to specific days or specific time blocks. Some teams do "Meeting Mondays and Thursdays." Others block 9-12 for meetings and protect afternoons.

The goal is to create contiguous maker time, not scattered 45-minute gaps.

Async Updates

Replace standup with a Slack thread. Replace status meetings with weekly written summaries. Replace "quick syncs" with Loom videos.

Async communication is searchable, referenceable, and doesn't fracture your calendar. Real-time meetings should be reserved for decisions, not information transfer.

Some developer intelligence platforms can automate this. They pull work from GitHub, Jira, and Slack to create weekly summaries without requiring humans to manually write status updates. You get the information transfer without the meeting.

The conversation with your manager looks like this:

"I know my deployment count looks lower than last quarter. Here's my fragmented time report. I had 4.2 hours of uninterrupted time per week last month. I'm not asking for special treatment. I'm asking for enough time to think."

Show the data. Propose the clustering solution. Most managers will say yes because they're also drowning in meetings.

Better Flow Improves DORA

Here's the irony: when you ignore DORA and optimize for flow, your DORA metrics usually improve.

A study of 10,000 programming sessions across 86 programmers found that only 10% of sessions resume coding in less than 1 minute after an interruption. The rest take significantly longer to rebuild context.

More fragmentation means more interruptions. More interruptions means more bugs. More bugs means lower change failure rate.

Better focus doesn't just make you feel better. It makes you faster and more accurate.

The Shopify example is instructive: after canceling recurring meetings with 3+ people, meeting time dropped 33% in two months. They expected to complete 25% more projects than the previous year.

That's better DORA performance from fewer meetings, not more sprints.

When you protect maker time, you write better code. Better code deploys faster and breaks less often. DORA metrics improve as a side effect of good engineering practices, not as a goal in themselves.

Your Dashboard Doesn't Define Your Worth

DORA metrics were designed to measure organizational performance, not individual productivity. The DORA team explicitly warns against using their metrics for team-by-team comparison or individual assessment.

Nicole Forsgren, who co-created DORA, went on to co-create the SPACE framework specifically because DORA was insufficient. The first letter in SPACE is S: Satisfaction and well-being. That was missing from DORA because DORA was never meant to capture the full developer experience.

Your deployment frequency says nothing about whether you had to sacrifice your weekend to hit that number. Your lead time doesn't show that you haven't shipped anything meaningful in months because you're constantly fixing the fragile system held together with technical debt.

Velocity is a management metric. Flow is a maker metric.

Your most valuable resource isn't your time. It's your attention span. Every meeting fragments it. Every interruption depletes it. Every context switch costs you 23 minutes of refocus time.

Protect your attention like it's your most valuable asset, because it is.

The green dashboard can wait. Your ability to think can't.

How do you protect your focus time? I'd love to hear what's worked (or hasn't) for dealing with meeting overload. Drop a comment below.