Rewrite the definition of a widget

Replaces what a widget shows with the definition in dsl. The whole definition travels, not the part of it that changes: the widget is rebuilt from it, exactly as the assistant of the application rebuilds one. Read it with /v1/widgets/get, change what you want and send it back.

What the rewrite KEEPS of the widget: the connection it reads through, the row and the column it is in, its format property by property, the comparison with the previous period of a KPI or a metrics summary, the literals of a custom period header, the breakdown by source and the deal pipeline of a HubSpot widget, the title of every column of a metrics summary whose metric is still there, and the internal notes unless internal_notes is sent. Two properties are kept only while the shape does not change, because the shape is what chooses them: the legend position (a pie hides it) and the headers of the periods (a metrics summary dates them). What it cannot keep comes back in lost_properties. /v1/capabilities publishes the whole list under widgets.update.

What it does NOT read: the integration of a widget cannot be changed, so there is no integration_id here; full_width is ignored, because the place of a widget belongs to the report and an update never moves anything.

Every call keeps the widget as it was first and answers with the backup_key that puts it back through /v1/widgets/restore, for 7 days. There is no confirmation step for that reason.

Refusals: 400 for the framework and the body, 400 APPEND_NOT_ALLOWED with reason template_based for a report built on a template -- where only the text widget the report keeps of its own can be changed -- 403 WRITE_ACCESS_DISABLED, 404 NOT_FOUND, 409 WIDGET_NOT_EDITABLE when the widget carries something the DSL cannot describe, 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 DATA_VIEW_CHANGED, 409 ROW_RULE when the new shape does not fit the row the widget is in, and 409 REPORT_IN_TRASH.

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

What a widget COMPARES is decided when it is created: this call does not change the class of a comparator, does not turn an ordinary widget into one and does not stop one being one, and a body that tries is refused with 400 VALIDATION_FAILED and the problem COMPARATOR_CLASS_FIXED. Whether it is broken down over time is part of that class: over_time moves from one axis to another, never from none to an axis or back. A body with no compare at all leaves the comparator exactly as it is -- the compared elements, the axis, the second series and the shape it is drawn as are kept -- and a body that carries one replaces them whole. A body with no compare keeps the order and the cap of the comparator too, so on a comparator not drawn as a trend a sort_by or a limit is refused with 400 VALIDATION_FAILED and the problem COMPARE_KEY_NOT_FOR_THIS_COMPARATOR (a dry run answers valid false with the same problem). The one cap a body with no compare does write is the one of a breakdown: its limit is the number of series it is broken down into, and a limit of null keeps the one it has. In a report whose report_level_data_sources is true the accounts of a comparator are the report's: send compare.items exactly as the read published them, every field of every item and in the same order, and a body that changes anything in them answers 409 NOT_ALLOWED with details.reason report_level_data_sources; nothing an item carries is accepted and dropped.