Plan a coordinated Custom API, data, and storefront release
Release a vertical slice in dependency order, with compatible states during rollout and a rehearsed recovery path for API, data, and storefront changes.
In this guide
Treat the release as one behavior change
A Custom API, its project-owned data, and a storefront feature often form one vertical slice. Deploying only the UI can expose a control whose backing contract is absent. Deploying only data can leave an incompatible reader. Planning by repository or team boundary hides these dependencies. Plan instead around the first and last request a user can make.
Write a manifest that names artifacts, versions, configuration prerequisites, migrations, feature gates, ownership, validation evidence, rollback or forward-correction approach, and communication. The manifest should identify which change is additive, which is backward compatible, and which requires a coordinated cutover.
This is an application-owned JSON contract for the project runbook and automation. Its field names are defined here; it is separate from Znode configuration and API request formats.
release-manifest.json json
{
"releaseId": "support-notes-2026-09",
"feature": {
"key": "account-support-notes",
"initiallyEnabled": false
},
"artifacts": [
{
"id": "project-data-002",
"kind": "project-owned-database-migration",
"change": "add-nullable-note-category",
"dependsOn": []
},
{
"id": "notes-api-1.4.0",
"kind": "custom-api",
"dependsOn": [
"project-data-002"
],
"acceptsContractVersions": [
1,
2
]
},
{
"id": "storefront-2.8.0",
"kind": "webstore",
"dependsOn": [
"notes-api-1.4.0"
],
"sendsContractVersion": 2
}
],
"activationChecks": [
"existing-note-readable-with-missing-category",
"new-note-readable-by-previous-client",
"cross-account-read-denied",
"feature-disabled-hides-entry-point",
"timeout-does-not-create-second-note"
],
"recovery": {
"firstAction": "disable-account-support-notes",
"retainCreatedRecords": true,
"databaseStrategy": "reviewed-forward-correction",
"previousApiRollbackRequires": "compatibility-with-data-already-written"
}
}Order changes for compatibility
Prefer additive data and API changes first. New readers should tolerate absent optional data while the migration is pending. New writers should not require a storefront version that has not arrived. Enable the user-facing feature only after the dependent artifacts pass their target-environment checks.
Do not edit an already executed migration as a rollback strategy. Journaled migrations and deployed data need forward corrections that account for actual state. For project-owned data, define whether a rollback removes a feature only, preserves new records, or performs a separately reviewed repair.
- Prepare versioned artifacts and deployment notes.
- Apply additive data prerequisites.
- Deploy API capable of old and new safe states.
- Deploy storefront with feature disabled.
- Run smoke and negative-path checks, then enable deliberately.
Test the seams
Smoke checks should cover the happy path and the states created by a staggered rollout: no new data, partial data, API unavailable, unauthorized user, stale storefront asset, and feature disabled. Include a readback query or application view that verifies the exact intended result without exposing secrets. A successful build is not a release verification.
Rehearse the recovery decision before the change window. If the API fails, can the feature be disabled without deleting records? If a migration partially applies, who owns the forward correction? If storefront content is cached, how will the team confirm that the expected asset is active? Assign names, not generic teams, in the internal runbook.
- Browser and API health checks.
- Authorized and unauthorized behavior.
- No-data and partial-migration behavior.
- Observability and alert paths.
- Recovery owner and decision threshold.
Record the deployed contract
Record the deployed artifact versions, target environment, activation time, and results of each named check alongside the manifest. Use immutable build identifiers in the deployment record so a support engineer can connect an observed request to the code and data contract serving it.
Treat rollback as another compatibility decision. Disabling the interface stops new user actions, but it does not cancel work already accepted or undo data already written. Keep the required worker and reader versions available until those records have a defined recovery path.
Verification checklist
Validate the manifest against the exact target platform and hosting model. Exercise the feature both before and after enabling it, then verify recovery in a permitted non-production environment. Recheck the guide when platform deployment guidance changes.
References and further reading
Bring your next engineering question.
Need help planning a safe commerce release?
Independent guidance from GCG. Znode is a trademark of its owner. Examples use fictional data and are not official platform documentation. Suggest a correction.