vishal patel
← Case studies
Tech lead · Contentstack platform

Branch creation API: controlled environment cloning

Creating a branch cloned every environment's publish configuration, whether you wanted it or not. I worked on an explicit, validated control that's still backward compatible.

api-designvalidationbackward-compatibilitybranching
Explicit control: clone all, none, or a chosen list
Omitting the field keeps the old behaviour — no breaking change
Validated at the API edge, so bad requests fail fast

Context

When a new branch is created, it can carry over publish configuration per environment (dev, staging, production…). Teams creating short-lived feature branches didn't always want production environments cloned into them.

Design: tri-state semantics on one field

diagram

Key decisions

  • Omitted ≠ empty. Treating "not provided" as "clone all" preserves the existing behaviour for every current client. [] is an explicit opt-out. This is a small but important API-design distinction.
  • Resolve and validate at the API layer before any job starts, so errors surface immediately rather than halfway through branch creation.
  • One field, three clear meanings, documented with examples, instead of adding several boolean flags.

Why it matters

It's a compact example of backward-compatible API evolution: additive, default-preserving, validated early. See API Evolution & Backward Compatibility.