Das Antwortformat: data und meta

Worum es geht

Alle Antworten von CDMS haben eine von wenigen festen Formen. Wer sie kennt, kann sie im Client an einer Stelle auswerten.

Die vier Formen

Welche Antwortform bekomme ich?

Anfrage	Erfolg?	Form der Antwort
create, read, update, patch, rollback	ja	SingleResponse: `data` ist ein Objekt
query	ja	QueryResponse: `data` ist eine Liste, `meta` enthält die Trefferzahlen
history	ja	AuditQueryResponse: `data` ist eine Liste von Revisionen
delete	ja	leerer Körper, Status 200
Datei-Download	ja	die Datei selbst, kein JSON
beliebig	nein	Fehlerantwort, siehe unten

Einzelobjekt

SingleResponse – Antwort auf create, read, update, patch, rollback

Anfrage

POST /api/rest/crm/customer/read/5a2b…
{ "response": ["name", "email"] }

Antwort 200

{
  "data": {
    "id": "5a2b…",
    "@type": "crm.customer",
    "_createdOn": "2026-09-21 10:12:00",
    "_updatedOn": null,
    "name": "Muster GmbH",
    "email": "info@muster.de",
    "address": null
  },
  "meta": { "error": false, "errorMessage": null, "notNull": false }
}

In data steht das DTO. Angeforderte Felder haben ihren Wert, nicht angeforderte stehen als null da.
id, @type, _createdOn und _updatedOn sind immer dabei.
meta ist bei einer Erfolgsantwort immer error: false. Die Felder haben für den Client keine weitere Bedeutung.

Liste

QueryResponse – Antwort auf query

Anfrage

POST /api/rest/crm/customer/query
{ "response": ["name"],
  "parameter": { "page": 1, "limit": 2 } }

Antwort 200

{
  "data": [
    { "id": "…", "name": "Beta AG", … },
    { "id": "…", "name": "Gamma KG", … }
  ],
  "meta": {
    "totalCount": 5,
    "currentPage": 1,
    "currentPageSize": 2,
    "currentLimit": 2,
    "error": false,
    "errorMessage": null
  }
}

`meta`-Feld	Bedeutung
`totalCount`	Anzahl aller Treffer über alle Seiten. Bei `"meta": false` im Request wird nicht gezählt
`currentPage`	die gelieferte Seite, beginnend bei 0
`currentLimit`	die angefragte Seitengröße
`currentPageSize`	wie viele Objekte tatsächlich auf dieser Seite stehen

Seitenzahl im Client: Math.ceil(totalCount / currentLimit). Keine Treffer sind kein Fehler: data ist dann eine leere Liste. Mehr dazu unter Blättern und Trefferzahl.

Historie

AuditQueryResponse – Antwort auf history

Anfrage

POST /api/rest/crm/customer/5a2b…/history
{ "response": ["name"] }

Antwort 200

{
  "data": [
    {
      "revision": { "id": "5a2b…", "name": "Muster GmbH", … },
      "revisionMeta": {
        "ref": 42,
        "ts": 1790000000000,
        "ip": "10.0.0.7",
        "useragent": "Mozilla/5.0 …",
        "username": "anna"
      },
      "revisionType": "MOD"
    }
  ],
  "meta": { "error": false, … }
}

Feld	Bedeutung
`revision`	das Objekt, wie es nach dieser Änderung aussah
`revisionMeta.ref`	Nummer der Revision, die du für einen Rollback brauchst
`revisionMeta.ts`	Zeitpunkt in Millisekunden seit 1970
`revisionMeta.ip`, `useragent`, `username`	wer die Änderung von wo gemacht hat
`revisionType`	`ADD` angelegt, `MOD` geändert, `DEL` gelöscht

Die neueste Revision steht zuerst. Siehe Historie lesen.

Fehler

Fehler haben eine eigene, flache Form ohne data:

Fehlerantwort – hier eine Validierung

Anfrage

POST /api/rest/crm/customer/create
{ "data": { "name": "" }, "response": ["id"] }

Antwort 422

{
  "error": "ApiValidationException",
  "messageKey": "validation-failed",
  "code": "422",
  "layer": "API",
  "violations": [
    { "field": "name",  "rule": "cannot-be-empty" },
    { "field": "email", "rule": "cannot-be-null" }
  ]
}

Feld	Bedeutung	im Client
`error`	Art des Fehlers	zum Protokollieren
`messageKey`	fester Schlüssel, z. B. `missing-permission\|customer-read`	hierauf verzweigen, nicht auf den Text
`message`	lesbarer Text	nur für Menschen
`code`	HTTP-Status als Text	wie der Status der Antwort
`layer`	Schicht, in der der Fehler entstand	zur Fehlersuche
`violations`	nur bei Validierungsfehlern: alle Verstöße mit Feldpfad und Regel	den Formularfeldern zuordnen
`id`	nur im Sonderfall unten	–

Welcher Code was bedeutet, steht unter Landkarte der Statuscodes. Wie Verstöße ins Formular kommen, unter Validierungsfehler ins Formular bringen.

Der Sonderfall: angelegt, aber nicht zurückgelesen

Nach einem create liest CDMS das Objekt für die Antwort zurück. Im Modus LENIENT kann das Anlegen gelingen und nur das Zurücklesen scheitern. Dann kommt eine Antwort in Fehlerform, aber mit Status 200 und der id des angelegten Objekts:

Antwort 200

{
  "error": "CreateSucceededReadFailedException",
  "messageKey": "CDMS_CREATE_SUCCEEDED_READ_FAILED",
  "code": "200",
  "layer": "system",
  "id": "5a2b…"
}

Was der Client tun sollte

Das Objekt existiert.
Mit der id später erneut lesen,
NICHT noch einmal anlegen.

Siehe Anlegen und Zurücklesen: STRICT oder LENIENT.

Eine Auswertung für alles

So wertet ein Client jede Antwort aus

1

Client
Status 2xx?
2

Client
ja, und messageKey ist CDMS_CREATE_SUCCEEDED_READ_FAILED → angelegt, id merken, später lesen
3

Client
ja, sonst → data verwenden, bei Listen zusätzlich meta
4

Client
nein → messageKey auswerten, bei 422 die violations den Feldern zuordnen, bei 401 Token erneuern und einmal wiederholen