Sections

Reorder the sections of a report

Puts the sections of a report in another order and raises the version of its sections structure.

section_keys carries the same keys /v1/reports/get publishes for the report, each of them once, in the order they are to be read: a list that adds, drops or repeats a key is refused with 400 INVALID_VALUE instead of being merged onto what is stored, and a list that stopped being an exact permutation between the read and the write is refused with 409 VERSION_MISMATCH inside the transaction that writes -- that one carries the version the report is at and the reason, and no expected, because what went stale was the list of sections and not a number the caller sent. Read the report, rearrange the keys it gave you, and send them back.

It accepts if_version and compares it again inside that transaction. It changes nothing about what any widget shows or reads, so no cached result is dropped.

A report built on a template is refused with 400 APPEND_NOT_ALLOWED, reason template_based: its sections, and their order, belong to its template.

Refusals: 400 for the framework and the body, 400 INVALID_VALUE, 400 APPEND_NOT_ALLOWED, 403 WRITE_ACCESS_DISABLED, 404 NOT_FOUND, 409 VERSION_MISMATCH, 409 SECTION_BUSY and 409 REPORT_IN_TRASH.

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

post/sections/reorder

Request

  • Base URL: https://api.reportingninja.com/v1
  • URL: https://api.reportingninja.com/v1/sections/reorder
  • Auth: HTTP bearer

Request body

report_keystring required

The report to reorder.

section_keysstring[] required

The SAME section keys /v1/reports/get publishes for the report, each of them once, in the new order. A list that adds, drops or repeats a key is refused.

if_versioninteger

The sections version of the report, as /v1/reports/get publishes it. A stale one is HTTP 409 VERSION_MISMATCH, compared again inside the transaction that writes.

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.

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.