From b7cfbf5f23d97f99026b449ee5d87d55ae20ab68 Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Thu, 18 Jun 2026 18:30:11 -0400 Subject: [PATCH] docs(frontend-guide): update event_file delete response shape and behavior Documents orphan_cleaned field, corrected hosted_file_link_cleaned semantics, and explains the for_type/for_id link targeting so frontend devs understand why the single-call endpoint is complete without extra params. Co-Authored-By: Claude Sonnet 4.6 --- documentation/GUIDE__AE_API_V3_for_Frontend.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/documentation/GUIDE__AE_API_V3_for_Frontend.md b/documentation/GUIDE__AE_API_V3_for_Frontend.md index a78bc98..9ae4763 100644 --- a/documentation/GUIDE__AE_API_V3_for_Frontend.md +++ b/documentation/GUIDE__AE_API_V3_for_Frontend.md @@ -355,14 +355,20 @@ Atomic delete that cleans up an event_file and its linked hosted_file in a singl | Query param | Type | Default | Description | |---|---|---|---| -| `rm_orphan` | bool | `true` | If `true` and no other links point to the hosted_file, also deletes the physical file and hosted_file DB record. Set `false` to only remove the event_file row and its link without touching the hosted_file. | +| `rm_orphan` | bool | `true` | If `true` and no other links point to the hosted_file after this one is removed, also deletes the physical file and hosted_file DB record. Set `false` to only remove the event_file row and its link. | **Response:** ```json -{ "event_file_deleted": true, "hosted_file_link_cleaned": true } +{ "event_file_deleted": true, "hosted_file_link_cleaned": true, "orphan_cleaned": true } ``` -`hosted_file_link_cleaned: true` means the hosted_file_link was removed successfully (and orphan cleanup ran if `rm_orphan=true`). It does not distinguish between "file was deleted" and "file has other links" — both are successful outcomes. +| Field | Meaning | +|---|---| +| `event_file_deleted` | Always `true` (the event_file row was removed). | +| `hosted_file_link_cleaned` | `true` if the `hosted_file_link` record was found and deleted. `false` if the link was already absent (e.g. a file uploaded before the V3 migration fix — the endpoint still continues with orphan cleanup). | +| `orphan_cleaned` | `true` if `rm_orphan=true`, no remaining links existed, and the physical file + `hosted_file` DB record were removed. `false` if other objects still reference the file, or `rm_orphan=false`. | + +> **Implementation note for frontend devs:** The `hosted_file_link` is created against the file's *parent object* (`for_type` / `for_id`, e.g. `event_presenter`) — not against `event_file` itself. The endpoint reads `for_type` and `for_id` from the `event_file` row to find and delete the correct link. You do not need to pass anything extra; `DELETE /v3/action/event_file/{id}` is a complete single-call operation. ---