Reading the history

What this is about

The history is the list of all revisions of an object, newest first. You read it with an endpoint of its own, which only exists for audited models and only if it is listed in the model’s endpoint list.

Request and response

POST /api/rest/order/7e1…/history
{
  "response": ["orderNr", "price"],
  "parameter": { "page": 0, "limit": 2 }
}

{ "data": [
    { "revision": { "id": "7e1…", "orderNr": "A-1000", "price": 99.0 },
      "revisionMeta": { "ref": 51, "ts": 1790000300000, "username": "Ben Beispiel", … },
      "revisionType": "MOD" },
    { "revision": { "id": "7e1…", "orderNr": "A-1000", "price": 120.5 },
      "revisionMeta": { "ref": 42, "ts": 1790000200000, "username": "Anna Muster", … },
      "revisionType": "MOD" }
  ],
  "meta": { "error": false, "totalCount": 0, "currentPage": 0, … } }

Every entry in data is a revision with three parts: revision (the state of the object), revisionMeta (who, when, from where) and revisionType (ADD, MOD, DEL). The fields of revisionMeta are explained in What a revision records.

What the request controls

+ and * do not bring the system fields _createdOn and _updatedOn in the history. You read the time of a revision from revisionMeta.ts. See Audit is not the same as system fields.

The checks

Both roles are defined in the model. Their names are explained in Model roles. In strict mode the error is missing-permission|<role>, without strict mode missing-read-role or missing-history-role. See Strict mode.

The roles say whether someone may read histories of this model – not which ones. That is decided by the same row filters as reading and searching: the owner filter and the attribute filters. Whoever cannot read an object does not get its history either.

For a deleted object there is no row left to check this against. CDMS uses the last revision before the deletion instead: it still carries the owner and the attribute values, and the filters are applied to it. The DEL revision is of no use for this, its fields are empty.

If a model has neither an owner nor an attribute filter, there is nothing to check – there the two roles decide on their own.

The variants

Decision table

On a model with a filter, an unknown id cannot be told apart from a hidden one: both result in 404. Otherwise the difference between the answers would tell a caller which foreign ids exist.

Paging

With page and limit you fetch the history in pages, just like a search. page starts at 0. If you leave out limit, all revisions come at once.

Unlike a search, the history does not fill meta: totalCount, currentPage and currentLimit are always 0. So you do not learn the total in advance. Keep paging until a page has fewer entries than limit.

Pitfalls

What comes next

• Restoring a state: Rolling back to an old state
• The response in detail: The response format
• How the endpoints are created: Which endpoints a model has