Incremental API Gateway Configuration: Rebuild Less, Verify More

Originally published by Yilia Lin on API7.ai.

This article was drafted with AI assistance.

A one-line route change should not require a platform to reconsider millions of unrelated objects. Yet many configuration pipelines do exactly that: they read a full desired state, rebuild a complete artifact, compare everything, and publish the small difference at the end. The output is incremental; the work is not.

Cloudflare made that distinction concrete in its November 2026 account of targeted DNS zone builds. Its Zone Builder had to process roughly 700 record changes and 100 other events per second while some zones exceeded 20 million records. A new planner chose the smallest build it could prove safe, while a scheduler combined compatible work. Cloudflare reports that this cut peak memory by 85% and halved the delay from a DNS change to its edge data store.

Those figures belong to Cloudflare's DNS pipeline; they are not an API gateway benchmark. The useful lesson from the Hacker News discussion is architectural: optimize the work behind a configuration change only after you can describe its scope, escalation path, retry semantics, and proof of equivalence.

Key Takeaways

• A small final diff can still hide an expensive full-state rebuild.
• Classify changes by what they can affect, not by the size of the incoming event.
• Unknown or newly incompatible state should escalate to full reconciliation.
• Combine work monotonically: merging two changes may widen scope, never silently narrow it.
• Keep delivery acknowledgement separate from the work plan so retries do not lose changes.
• Prove targeted and full paths produce equivalent state before making the targeted path authoritative.

Separate the Event, Plan, and Desired State

A configuration event says something happened. It does not necessarily contain enough information to produce the correct runtime state.

Consider an API platform event that says a route changed. The route may reference a shared service, upstream, plugin configuration, certificate, consumer group, or global rule. A field that looks local in the user interface may alter many effective routes after inheritance and references are resolved. Deleting an object may require removing previously generated state that is no longer present in the new snapshot.

Treat configuration delivery as explicit stages:

The event supplies a hint. The planner turns that hint into conservative work. The builder reads fresh state before execution, because the desired state may have changed while the event waited. Publication happens only after validation.

This distinction reduces the risk that a stale event becomes the source of truth. It also gives the system a safe answer when it cannot prove a narrow scope: do more work.

Classify by Blast Radius

An incremental planner needs an explicit classification table. Start with categories that reflect effective runtime impact:

The table is not universal. A platform with flattened configuration has different dependencies from one that resolves references in the data plane. The important property is that every narrow class has documented prerequisites and a deterministic full-work fallback.

Cloudflare's design rechecks current state immediately before work. A targeted build can become a full build, a purge, or a no-op when fresh state changes the answer. API gateway pipelines need the same direction of safety: new evidence may expand or cancel work, but it should not preserve a narrow plan that is no longer justified.

Combine Work Without Losing Intent

Bursty control planes often receive several changes for the same gateway scope before the first build starts. Rebuilding after every event wastes capacity and can publish intermediate states no caller needs.

A scheduler can combine work by taking the union of affected objects. If one pending change requires full reconciliation, the combined plan becomes full. If a resource is deleted or a deployment scope is removed, the purge must dominate an ordinary update. This is a monotonic rule: combination can add required work, not subtract it.

Acknowledgement needs a separate ledger. A compact work plan might say “rebuild routes A and B,” while five source events are waiting for durable completion. Retrying the plan must retain all five event identities until the output is safely published. Cloudflare explicitly chooses repeated work over losing a change when its Kafka consumer restarts. Configuration systems should make the same trade when correctness matters more than avoiding an idempotent replay.

Fairness matters too. A noisy tenant or gateway group should not occupy every worker while unrelated updates wait. Per-scope coalescing, concurrency limits, age-based priority, and retry backoff reduce the risk that one hot configuration domain becomes a control-plane denial of service.

Prove Equivalence Before Optimizing

The hardest part of incremental delivery is not selecting less work. It is proving that the smaller path produces the same effective state as the reference full path.

Use four layers of evidence:

1. Dependency fixtures. Cover local updates, shared references, deletions, renames, inheritance, and global-policy escalation.
2. Byte- or semantic-equivalence tests. Build targeted and full outputs from the same pinned inputs, then compare the owned runtime objects. Normalize fields only when their differences are intentionally non-semantic.
3. Shadow reconciliation. Run the optimized planner against production-shaped events, but publish to an isolated target. Compare missing, extra, and changed objects after both sides have caught up.
4. A rollback trigger. New persistent difference classes, queue-age growth, or validation failures should disable the targeted class and return it to full reconciliation.

Temporary differences are not automatically defects when two pipelines observe state at different moments. Compare at a defined convergence point, record the input revision, and distinguish lag from a persistent semantic mismatch.

This verification pattern is more valuable than copying any particular planner. It gives the optimization an expiration condition: when the proof fails, the full path remains available.

Map the Pattern to APISIX and ADC Carefully

Apache APISIX does not use Cloudflare's DNS builder, and this article does not claim it implements the planner above. The connection is the configuration boundary.

The Apache APISIX 3.19 deployment-mode documentation distinguishes traditional, decoupled, and standalone deployments. File-driven standalone mode checks a YAML or JSON file and hot-reloads rules when the file changes; API-driven standalone updates replace the full in-memory configuration. Traditional and decoupled modes use a configuration center. These modes have different update units, ownership paths, and recovery tests, so an optimization validated for one mode should not be generalized to the others.

For declarative delivery, the pinned ADC workflow provides a useful release boundary: adc lint, adc validate, adc diff, then adc sync. sync reconciles resources inside its command scope and can delete an in-scope remote resource that is absent locally. Gateway groups, label selectors, and resource-type filters therefore define ownership, not merely convenience flags.

That workflow answers “is this desired state valid and what will change?” It does not by itself prove that a custom incremental compiler produces equivalent runtime state. If you add a planner around it, preserve the validated scope and compare the resulting effective configuration.

API7's earlier explanation of label-scoped declarative configuration shows why ownership boundaries matter when several teams manage one backend. The broader API deployment practices add canary and rollback context after configuration has been built.

A Safe Rollout Checklist

Before enabling incremental configuration work for a class of changes, require:

• a named owner and source-of-truth revision;
• a dependency map for shared and inherited objects;
• a full-reconciliation fallback;
• idempotent publication or a documented deduplication key;
• retained event acknowledgement across retries;
• targeted-versus-full equivalence tests;
• shadow comparisons using production-shaped state;
• queue age, build duration, memory, and mismatch telemetry;
• a per-scope fairness limit and retry backoff;
• a tested rollback that does not discard pending changes.

Optimize one class first. Route-local metadata is usually easier to bound than certificates, global rules, or identity policy. Keep the full path scheduled periodically even after the targeted path is stable; it detects drift that no individual event exposed.

Correctness Is the Performance Feature

Incremental configuration is attractive because it can reduce memory, latency, and unnecessary work. Its real value is predictable change: a platform knows why a narrow update is sufficient, when it must widen scope, and how it proves the outcome.

Start by instrumenting one expensive configuration path. Measure work performed, not only the size of the published diff. Classify its dependencies, preserve a full reconciliation path, and run both builders until their outputs converge reliably. Then the gateway control plane can rebuild less without asking operators to trust more.

To apply the pattern to a managed gateway fleet, review API7 Enterprise and the API7 Gateway documentation alongside the exact deployment mode and release you operate.