By d34dman on
Change record status: 
Draft (View all draft change records)
Project: 
FlowDrop
Introduced in branch: 
2.7.x
Introduced in version: 
2.7.0
Issue links: 
https://www.drupal.org/node/3592420
Description: 

Seven FlowDrop API routes moved under /api/flowdrop/, so that a refusal thrown before their
controller runs (an access 403, a router 404) is answered as JSON with an error_code, like every other
/api/flowdrop/* endpoint. Route names are unchanged, so code that builds these URLs with
Url::fromRoute() follows automatically.

The old paths keep working for the rest of 2.x as deprecated aliases (route names suffixed .legacy)
and are removed in 3.0. They behave exactly as before, including how they refuse: a 403 or 404
thrown before the controller runs keeps Drupal's default response and carries no error_code.

Moved paths

Route name (unchanged) Old path (deprecated) New path
flowdrop_interrupt.api.pipeline.cancel 
POST
/flowdrop/api/pipelines/{pipeline_id}/cancel
 
POST
/api/flowdrop/pipeline/{pipeline_id}/cancel
flowdrop_interrupt.api.pipeline.pause 
POST
/flowdrop/api/pipelines/{pipeline_id}/pause
 
POST
/api/flowdrop/pipeline/{pipeline_id}/pause
flowdrop_interrupt.api.pipeline.resume 
POST
/flowdrop/api/pipelines/{pipeline_id}/resume
 
POST
/api/flowdrop/pipeline/{pipeline_id}/resume
flowdrop_runtime.api.snapshot.get 
GET
/api/flowdrop-runtime/snapshot/{execution_id}
 
GET
/api/flowdrop/snapshot/{execution_id}
flowdrop_runtime.api.snapshot.delete 
DELETE
/api/flowdrop-runtime/snapshot/{execution_id}
 
DELETE
/api/flowdrop/snapshot/{execution_id}
flowdrop_runtime.api.snapshot.save 
POST
/api/flowdrop-runtime/snapshot
 POST /api/flowdrop/snapshot
flowdrop_runtime.api.snapshot.list 
GET
/api/flowdrop-runtime/snapshots
 GET /api/flowdrop/snapshots

Before

curl -X POST https://example.com/flowdrop/api/pipelines/42/pause
curl https://example.com/api/flowdrop-runtime/snapshots

After

curl -X POST https://example.com/api/flowdrop/pipeline/42/pause
curl https://example.com/api/flowdrop/snapshots

Code that builds the URL from the route name needs no change:

$url = Url::fromRoute('flowdrop_interrupt.api.pipeline.pause', ['pipeline_id' => 42]);
// 2.6.0: /flowdrop/api/pipelines/42/pause
// 2.7.0: /api/flowdrop/pipeline/42/pause

Finding callers of the old paths

Every call to an old path is answered with:

  • a Deprecation response header (RFC 9745) carrying the date the path was deprecated,
  • a Link: <new path>; rel="successor-version" header,
  • a flowdrop log notice: "Deprecated FlowDrop API path … was called; it is removed in 3.0. Use …
    instead."

No Sunset header is sent, because 3.0 has no date yet.

Custom editor endpoint configuration

The editor shipped with FlowDrop already calls the new paths: its endpoint configuration declares the
signals group relative to the API base, with no baseUrl of its own. A host that builds its
own endpoint configuration and sets signals.baseUrl to …/flowdrop/api keeps working against
the deprecated aliases until 3.0. Drop that override, and use /pipeline/{pipelineId}/pause (and
resume, cancel) under the API base:

// Before (2.6.0)
'signals' => [
  'baseUrl' => '/flowdrop/api',
  'pause' => '/pipelines/{pipelineId}/pause',
  'resume' => '/pipelines/{pipelineId}/resume',
  'cancel' => '/pipelines/{pipelineId}/cancel',
],

// After (2.7.0)
'signals' => [
  'pause' => '/pipeline/{pipelineId}/pause',
  'resume' => '/pipeline/{pipelineId}/resume',
  'cancel' => '/pipeline/{pipelineId}/cancel',
],

Updating

Run the database updates after updating the code. A post-update
(flowdrop_runtime_post_update_move_api_routes) makes sure the router is rebuilt; until it is, the new
paths answer 404 and pause, resume and cancel fail in the editor.

drush updb
drush cr
Impacts: 
Site builders, administrators, editors
Module developers
Site templates, recipes and distribution developers