>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588775. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>When <code>POST /api/page</code> is sent with <code>{"path":{"alias":"/foo"}}</code>, the alias is silently ignored. The response is HTTP 201 (success) and the page entity is created, but the <code>path.alias</code> field in the response body and on subsequent GETs shows <code>none</code> (or null). There is no error, no warning, no indication that the alias request was dropped. Setting the alias requires a separate write after page creation &mdash; a two-step operation, not one-shot.</p> <p>Any agent or script that creates canvas pages and assumes the alias is set in the same call will produce pages that are unreachable at their expected URLs. Affected paths:</p> <ul> <li><code>content-composer.md</code> &mdash; if it creates pages via <code>canvas:page:create</code> and assumes the alias is live immediately.</li> <li>The Phase 8 completion gate (issue 1-06) &mdash; verifies pages by URL; unaliased pages will appear missing.</li> <li>Any content-template phase that creates canvas pages as part of the workflow.</li> <li>Menu items (2-05 / 2-01 / 2-02) that reference page paths &mdash; the URI must point to a valid alias for navigation to resolve.</li> </ul> <p>Empirical evidence: a probe page created on 2026-05-01 with <code>{"path":{"alias":"/probe-delete-me-..."}}</code> returned HTTP 201, but a subsequent GET showed <code>path.alias = none</code>. Probe page UUID <code>ef9c3962-a7dd-4b06-91d0-230c1ae68a75</code> (created and deleted during scope-probe Phase 7).</p> <p><strong>Update 2026-05-11:</strong> Re-probed today against the live test instance and against the <code>/api</code> JSON:API discovery doc. Confirmed: <code>POST /api/page</code> still silently ignores <code>path.alias</code>, but the Step 2 proposed workaround <strong>does not work</strong> &mdash; <code>path_alias</code> is NOT in the discovery doc (full inventory: <code>menu_items--*</code>, <code>page</code>, <code>file--file</code>, <code>media--*</code>, <code>taxonomy_term--*</code>, <code>node--article</code>, <code>node--person</code> &mdash; 20 types total, no <code>path_alias</code>). The only remaining workaround candidates are: (a) <code>PATCH /api/page/{uuid}</code> with the alias field (untested; the Open question below); (b) browser-automation via the Drupal admin URL-alias form at <code>/admin/config/search/path/add</code>. Recommendation: implementation must verify (a) before relying on it.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Request an OAuth token with <code>scope="canvas:page:create canvas:page:read canvas:page:delete"</code>.</li> <li>POST to <code>/api/page</code> with body <code>{"title":"PROBE","path":{"alias":"/probe-alias-test"}}</code> and the token.</li> <li>Observe: HTTP 201, <code>data.id</code> populated.</li> <li>GET <code>/api/page/&lt;uuid&gt;</code> with the token. Observe: <code>data.attributes.path</code> shows <code>{"alias": null}</code> or <code>"none"</code>, NOT the requested <code>/probe-alias-test</code>.</li> <li>Confirm: the alias was silently dropped during creation; no error or warning was issued.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p><strong>Step 1 &mdash; Reproduce on next page creation to lock in the bug:</strong></p> <pre>TOKEN=$(curl -sX POST $SITE/oauth/token \ -d "grant_type=client_credentials&amp;client_id=$CLIENT_ID&amp;client_secret=$CLIENT_SECRET&amp;scope=canvas:page:create canvas:page:read canvas:page:delete" \ | jq -r .access_token) UUID=$(curl -sX POST -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ "$SITE/api/page" \ -d '{"title":"PROBE-ALIAS-TEST","path":{"alias":"/probe-alias-test"}}' \ | jq -r .data.id) curl -sH "Authorization: Bearer $TOKEN" "$SITE/api/page/$UUID" \ | jq '.data.attributes.path' # Expected: {"alias": "/probe-alias-test"} -- ACTUAL: {"alias": null} or "none" curl -sX DELETE -H "Authorization: Bearer $TOKEN" "$SITE/api/page/$UUID"</pre><p><strong>Step 2 &mdash; Confirm the two-step workaround.</strong> After page creation, issue a separate alias write via JSON:API <code>path_alias--path_alias</code>:</p> <pre>curl -sX POST -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/vnd.api+json" \ "$SITE/api/path_alias/path_alias" \ -d "{\"data\":{\"type\":\"path_alias--path_alias\",\"attributes\":{\"path\":\"/canvas-page/$UUID\",\"alias\":\"/probe-alias-test\",\"langcode\":\"en\"}}}"</pre><p>Alternatively, probe whether <code>PATCH /api/page/{uuid}</code> with <code>{"path":{"alias":"/foo"}}</code> is honored after creation (PATCH may behave differently than POST for this field). Verify both paths and document which one works.</p> <p><strong>Step 3 &mdash; Update <code>.claude/agents/content-composer.md</code></strong> with an explicit note immediately before any page-creation step:</p> <pre>NOTE: canvas:page:create (POST /api/page) does NOT set path.alias inline. The path.alias field in the request body is silently ignored on this Acquia Source release. After creating a page, issue a SEPARATE write to set the alias: - POST /api/path_alias/path_alias with the page's Drupal path + desired alias OR - PATCH /api/page/{uuid} with {"path":{"alias":"/foo"}} (verify this works &mdash; not confirmed) Do NOT assume one-shot page creation sets the alias. Always verify alias with a GET after creation.</pre><p><strong>Step 4 &mdash; Add to <code>docs/migration/gotchas.md</code> under "Canvas API":</strong></p> <pre>- canvas:page:create (POST /api/page) silently ignores path.alias in the request body. Always issue a separate path_alias write after page creation. Verify alias with GET before adding the page to any menu or navigation.</pre><p><strong>Step 5 &mdash; Update page-checklist templates.</strong> Any JSON template for the page-creation step must show alias-setting as step 2 (separate from the create call), not part of step 1.</p> <p><strong>Step 6 &mdash; Search canvas project issue queue.</strong> Check the Drupal.org canvas project for an existing "path alias inline ignored" issue. If found, cite the issue number in <code>gotchas.md</code> so future agents can track resolution. If absent, file an upstream issue.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Re-confirm the bug with a fresh probe per Step 1.</li> <li>Confirm the two-step workaround per Step 2 (test both <code>path_alias</code> POST and <code>PATCH /api/page/{uuid}</code>).</li> <li>Add the explicit note to <code>.claude/agents/content-composer.md</code> per Step 3.</li> <li>Add the entry to <code>docs/migration/gotchas.md</code> per Step 4.</li> <li>Update page-checklist templates to show alias-setting as a separate step.</li> <li>Search/file an upstream canvas project issue per Step 6.</li> <li>Verify Phase 8 gate logic accounts for two-step alias creation: pages created without aliases must not be marked verified by URL until the alias write completes.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None.</p> <h3 id="summary-api-changes">API changes</h3> <p>None introduced. The fix consumes existing endpoints: <code>POST /api/page</code> (canvas page create), <code>POST /api/path_alias/path_alias</code> (separate alias write), and possibly <code>PATCH /api/page/{uuid}</code> for the post-create alias-set variant.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>New <code>gotchas.md</code> entry under "Canvas API". Updated page-checklist JSON template structure: alias is a separate step, not an attribute of the create step.</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-2-Determinism/07-NEW-12-canvas-page-path-alias-not-honored.md</code> (id: NEW-12)</li> <li>Empirical probe evidence: <code>RESEARCH-2026-04-28/99-final/SCOPE-PROBE-FINDINGS-2026-05-01.md</code> &sect; 5 ("canvas:page:create IGNORES path.alias inline")</li> <li>Compaction-persistence target: 1-07 (gotchas.md must include this)</li> <li>Phase 8 gate impact: 1-06 (path alias affects completion verification)</li> <li>Page composition workflow: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-8-Patterns-To-Encode/02-NEW-2-canvas-content-templates-phase.md</code> (Phase 4.5 creates pages)</li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>Does <code>PATCH /api/page/{uuid}</code> with <code>{"path":{"alias":"/foo"}}</code> work for setting the alias after creation? If yes, that is simpler than creating a separate <code>path_alias</code> entity. Probe before implementing the workaround.</li> <li>Is this a known canvas_oauth upstream bug? Search <code>https://www.drupal.org/project/canvas/issues</code> for "path alias" or "path.alias ignored". If filed, cite the issue number; the fix timeline determines whether this gotcha is "permanent" or "temporary pending upgrade."</li> </ul>