Widgets

Put a widget back from a backup

Puts the definition and the format a backup holds back onto the widget it was taken from. Every /v1/widgets/update and every /v1/widgets/restore keeps the widget as it was first, for 7 days, and /v1/widgets/get lists what is there under backup_keys.

The place and the connection are the CURRENT ones and not the backup's: a widget that was moved stays where it is and one that was rebound keeps reading what it reads. What comes back is what it showed and how it looked. The call takes a backup of its own before it writes, so a restore is undoable in the same way.

Refusals: 400 for the framework and the body, 400 APPEND_NOT_ALLOWED with reason template_based, 403 WRITE_ACCESS_DISABLED, 404 NOT_FOUND for the report, the section, the widget or a backup that is not this widget's, 409 WIDGET_NOT_EDITABLE, 409 WIDGET_CHANGED when if_widget_hash is stale or when the widget changed after the call read it (nothing is written and no backup is kept), 409 ROW_RULE and 409 REPORT_IN_TRASH.

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

post/widgets/restore

Request

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

Request body

report_keystring required
section_keystring required
widget_keystring required

The widget to put back. The backup has to be one of ITS backups.

backup_keystring required

From the backup_keys of /v1/widgets/get, or from the backup_key an update answered. A backup of another widget or of another account is HTTP 404 NOT_FOUND.

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 call is refused when the widget changed in between, so a restore never undoes an edit nobody has seen. A stale one is HTTP 409 WIDGET_CHANGED and details.stored_hash carries the current value; read the widget again and retry with the new hash AND THE SAME idempotency_key, which is accepted because if_widget_hash is not part of what that key identifies.

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.