Widgets

Delete a widget

Deletes one widget of a section. There is no undo. This endpoint ALWAYS asks for a confirmation: the first call answers HTTP 200 with confirmation_required, a token and a preview of the widget, including parallel_copies -- how many copies of this widget live in the reports built on this template, all of which are DELETED with it. That number is what the confirmation is for: deleting one widget of a template removes it from every report that follows the template. if_version is not accepted: deleting a widget does not change the list of sections the version covers. if_widget_hash IS accepted, and refuses the deletion with 409 WIDGET_CHANGED when the widget was rewritten between the call that read it and this one. Refusals: 400 for the framework and the body, 403 WRITE_ACCESS_DISABLED, 404 NOT_FOUND for the report, the section or the widget, 409 for the confirmation and idempotency conflicts.

Every write endpoint reads dry_run and idempotency_key; see the Write guarantees section of the introduction.

post/widgets/delete

Request

  • Base URL: https://api.reportingninja.com/v1
  • URL: https://api.reportingninja.com/v1/widgets/delete
  • Auth: HTTP bearer

Request body

report_keystring required
section_keystring required
widget_keystring required

The widget to delete. It must belong to that section of that report.

dry_runboolean

Validate and answer what WOULD happen, without writing anything. Default false.

idempotency_keystring

Makes a retry safe: the answer of the first call is replayed for 24 hours to any later call with the same key and the same body.

if_widget_hashstring

The widget_hash /v1/widgets/get published for this widget. The deletion is refused with HTTP 409 WIDGET_CHANGED when the definition changed in between, so a widget somebody has just rewritten is not deleted under the answer you read. The confirmation token does not cover this: it is bound to the body, and the body of a deletion says nothing about what the widget contains.

confirmation_tokenstring

The token the previous call answered. Sending the same body with it performs the write.

Response

The call succeeded. This endpoint reports its errors with a real HTTP status, so a 200 always carries status=ok.

status'ok' required

Changes

No recorded changes to this operation across all 1 revision of this API.