>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3591542. --> Reported by: [d34dman](https://www.drupal.org/user/751698) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The published BC policy at docs/reference/api/bc-policy.md previously claimed FlowDrop's REST API was stable starting with 1.0.0 and that response structure was additive-only ("existing fields will not be removed or renamed"). That promise does not match how the codebase is actually evolving.</p> <p>The HTTP endpoints under /api/* (flowdrop_pipeline, flowdrop_playground, flowdrop_interrupt, flowdrop_job, flowdrop_trigger, flowdrop_runtime snapshot, flowdrop_chat) exist to serve the bundled @flowdrop/flowdrop JavaScript library &mdash; the FlowDrop Editor and Playground components &mdash; and the wire format is dictated by what the editor of a given version needs to render and operate on. Every controller class is already marked @internal. The 1.4 cycle alone reshaped at least two endpoints (pipeline node_statuses field renames, playground /messages cursor + hasMore restructure) in ways that violate the additive-only claim.</p> <p>We need the documented policy to match the contract that has always actually been in force.</p> <p>Replace the "REST API Stability" section in docs/reference/api/bc-policy.md with an "HTTP API Stability" section that:</p> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>Replace the "REST API Stability" section in docs/reference/api/bc-policy.md with an "HTTP API Stability" section that:</p> <ul> <li>States that /api/* endpoints are @internal, served to the bundled JS library, and not a public REST contract.</li> <li>Spells out that paths, query params, request bodies, and response shapes may change between minor releases without a deprecation cycle.</li> <li>Explains the technical reasoning so the choice is auditable:</li> <li>Editor features extend the wire shape; freezing the shape would freeze editor evolution.</li> <li>The module and the bundled editor are versioned and shipped together &mdash; one client, one server, version-matched by construction, so the standard motivation for REST stability doesn't apply.</li> <li>URL versioning (/api/v1, /api/v2) would duplicate controller code and security surface for no consumer benefit.</li> <li>This matches Drupal core's posture on its internal AJAX / layout-builder / big-pipe / CKEditor endpoints.</li> <li>Points consumers needing a stable programmatic interface at the @api PHP layer (FlowDropNodeProcessor, Orchestrator, Trigger, Workflow Executor, StateGraph).</li> <li>Invites anyone with a genuine HTTP-client use case to open an issue so a deliberately-stable surface can be considered separately.</li> </ul> <p>Update CHANGELOG.md with a callout at the top of the [1.4.0] entry linking to the new section, and drop the "&#9888; breaking" framing from the two /api/* shape-change bullets.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <h3 id="summary-ui-changes">User interface changes</h3> <h3 id="summary-api-changes">API changes</h3> <p>No code changes. PHP @api surface unchanged. HTTP endpoints' @internal status was always true at the class level; this issue only updates the published BC policy to match.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>None</p>