Rename a frame with OnPress API v2 — PATCH /frames slug, references, rebake

Early frames were named by transliterating their human name: shapka-sajta (“site header”), vrezka-voprosy-i-otvety (“FAQ insert”). The slug passes validation, but it says nothing about where the frame goes: block, element and modifier are derived from the slug, so such a frame is a block of its own, and GET /frames?block=site does not find it. Renaming moves it to block__element naming — site__header, article__faq — without re-uploading anything.

1. Look at the frame and who uses it

GET /frames/{ref} returns the frame with its markup and, when other frames insert it with op/frame, their slugs in referenced_by.

curl -s -H "Authorization: Bearer $OP_TOKEN" "$BASE/frames/shapka-sajta?blog_id=233"

{
  "success": true,
  "blog_id": 233,
  "frame": {
    "id": "cb7ccee58078d1fb",
    "name": "Шапка сайта",
    "slug": "shapka-sajta",
    "block": "shapka-sajta",
    "element": null,
    "modifier": null,
    "inserts": { "op/lang-switcher": 2, "op/menu": 1 },
    "frame_refs": [],
    "binds": 8,
    "option": "onpress_frame_cb7ccee58078d1fb",
    "html": "…",
    "…": "…"
  }
}

No referenced_by here: no frame includes this header by name, so the rename touches nothing but the frame itself. A frame that is included looks like this:

{
  "success": true,
  "blog_id": 233,
  "frame": {
    "id": "35552939b0ea754f",
    "name": "Врезка: вопросы и ответы",
    "slug": "vrezka-voprosy-i-otvety",
    "sources": ["faq"],
    "renders_on_request": true,
    "referenced_by": ["obolochka-so-vstavkoj"],
    "…": "…"
  }
}

2. Make sure the new slug is free

A slug is unique within the site. GET /frames/site__header answering 404 means it is free:

{
  "success": false,
  "error": "frame_not_found",
  "message": "there is no frame \"site__header\" on this site",
  "ref": "site__header"
}

If it is taken, the rename is refused with 409 slug_taken and nothing changes — the answer names the frame that holds the slug:

{
  "success": false,
  "error": "slug_taken",
  "message": "slug \"site__header\" is already used by frame 164ec859ae2d9cfa; to replace its markup use PUT /frames/site__header",
  "slug": "site__header",
  "id": "164ec859ae2d9cfa"
}

Then decide which of the two frames is the real header: either delete the other one, or rename it out of the way first.

3. Rename

PATCH /frames/{ref} changes slug and name without touching the markup (a frame has no url — the address belongs to the page). Send name along to keep the human name in step with the slug.

curl -s -X PATCH -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  "$BASE/frames/shapka-sajta" -d '{"blog_id": 233, "slug": "site__header", "name": "Site: header"}'

When other frames include the renamed one, the answer lists what was rewritten. This is the rename of faq to article__faq on the staging site, included by two shells:

{
  "success": true,
  "blog_id": 235,
  "frame": { "id": "4b0e7c21d9a3f610", "slug": "article__faq", "name": "Статья: FAQ", "block": "article", "element": "faq", "modifier": null },
  "renamed": {
    "from": "faq",
    "to": "article__faq",
    "frames_updated": ["article", "landing"],
    "details": [
      { "id": "91399e3637b7aa2b", "slug": "article", "replaced": 1 },
      { "id": "…", "slug": "landing", "replaced": 1 }
    ]
  },
  "bake": { "status": "ok" },
  "rebaked": { "status": "ok", "frames": ["…"] }
}

There is no dry_run for a rename; referenced_by from step 1 is the preview of frames_updated. PATCH with neither slug nor name is 400 nothing_to_update, and a new slug that breaks the block__element--modifier scheme is 400 invalid_slug.

4. What changes and what does not

Where	What happens
the frame itself	new `slug` and `name`; `block`, `element`, `modifier` derived again; the id and the markup stay
frames that include it by slug	`<!-- wp:op/frame {"ref":"<old>"} /-->` becomes the new slug in their source; registry entry updated; baked again in the same call
the rest of their markup	untouched, byte for byte
frames that include it by id	nothing to rewrite
pages bound to it	untouched: `_onpress_frame` holds the id, not the slug
old `op/frame {"type":…}` references	not rewritten: they go through the legacy defaults, not by name

The rewrite and the registry update happen in one transaction. The bake that follows is reported in bake (the renamed frame) and rebaked (the frames that include it); rebaked is absent when nothing includes the frame. A failed bake does not undo the rename — bake again with POST /frames/rebake: {"frames": ["site__header"]} bakes the frames that include it, {"all": true} every frame of the site.

Check

GET /frames/site__header answers with "block": "site", "element": "header", and the same id as before. GET /frames/shapka-sajta is now 404 frame_not_found. Every slug from the old referenced_by shows the new name in its frame_refs, and GET /frames/<includer> shows op/frame {"ref":"site__header"} in its markup. Pages bound to the frame open exactly as before.

1. Look at the frame and who uses it

2. Make sure the new slug is free

3. Rename

4. What changes and what does not

Check

See also