Einträge

Ein Eintrag ist eine Zeile in einem Grid. Die Pfade liegen unter …/spaces/{spaceId}/grids/{gridId}/entities.

Methode	Pfad	Rolle
GET	…/entities	reader
POST	…/entities	creator
GET	…/entities/{entityId}	reader
PUT	…/entities/{entityId}	writer
POST	…/entities/{entityId}/update	writer
DELETE	…/entities/{entityId}	writer
GET	…/entities/{entityId}/events	reader

Layouts: wie Feldwerte geschrieben werden

Ein Eintrag hat kein festes Schema. Welche Schlüssel er trägt, entscheidet der Parameter layout — beim Lesen wie beim Schreiben.

layout	Schlüssel ist	Rumpf
field	die Feld-ID	{ "6512cc…": "Wert" }
indexed	keiner, Reihenfolge zählt	{ "fields": ["Wert", null, 3] }
key	der Feld-Schlüssel	{ "titel": "Wert" }
keyAndField	Schlüssel oder ID, gemischt	{ "titel": "Wert", "6512dd…": 3 }
property	der Feld-Name	{ "Titel": "Wert" }

Gelesene Einträge tragen zusätzlich _id mit der Kennung des Eintrags.

Die Vorgabe unterscheidet sich zwischen Lesen und Anlegen

Beim Lesen und Ändern gilt ohne layout das field-Layout. Beim Anlegen über POST …/entities gilt ohne layout dagegen indexed.

Wer beim Anlegen ein Objekt mit Feld-IDs schickt, ohne ?layout=field zu setzen, bekommt 400 mit der Meldung, dass das Format kein indiziertes Eintragsformat sei.

Welches Layout wofür

• field ist die sichere Wahl für Integrationen. Feld-IDs bleiben stabil, auch wenn jemand die Spalte umbenennt oder verschiebt.
• indexed ist die kompakteste Form, aber die zerbrechlichste: es müssen genau so viele Werte kommen, wie das Grid Felder hat, in Schemareihenfolge. Ein neues Feld bricht jeden Aufrufer.
• key und keyAndField sind lesbar und trotzdem haltbar, sofern Sie den Feldern Schlüssel geben (POST …/ColumnKeyChange).
• property ist für schnelle Handgriffe gedacht: der Feldname ändert sich, sobald jemand die Spalte umbenennt.

Fehlende Werte

Bei field, key, keyAndField und property bleiben nicht genannte Felder unangetastet. Bei indexed gibt es keine Auslassung — nicht gesetzte Werte werden als null übergeben.

Einträge lesen

curl -s -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  "$BASE$GRID/entities?layout=field&pageSize=100&pageIndex=1"

{
  "page": 1, "pageSize": 100, "size": 2, "numberOfItems": 2, "numberOfPages": 1,
  "items": [
    {
      "_representation": "full",
      "_id": "6512ef…",
      "6512cc…": "Erste Aufgabe",
      "6512dd…": "2026-04-01",
      "_links": {
        "self":   { "href": "…/entities/6512ef…", "method": "get" },
        "update": { "href": "…/entities/6512ef…", "method": "put" },
        "remove": { "href": "…/entities/6512ef…", "method": "delete" }
      }
    }
  ]
}

Parameter	Vorgabe	Bedeutung
pageIndex	1	Seite, 1-basiert
pageSize	300	Einträge je Seite
layout	field	Form der Werte
viewId	–	Kennung eines Virtual Grid: liefert dessen Ausschnitt
filter	–	Filter als JSON, URL-kodiert
sorting	–	Sortierung als JSON, URL-kodiert
compose	true	Ob filter mit dem Filter der Ansicht kombiniert wird oder ihn ersetzt

→ Paginierung und Filter

Ein einzelner Eintrag:

curl -s -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  "$BASE$GRID/entities/$ENTITY_ID?layout=field"

Eintrag anlegen

# Vorgabe: indexed
curl -s -X POST -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"fields": ["Erste Aufgabe", "2026-04-01", null]}' \
  -D - -o /dev/null \
  "$BASE$GRID/entities"

# Nach Feld-ID
curl -s -X POST -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"6512cc…": "Erste Aufgabe"}' \
  -D - -o /dev/null \
  "$BASE$GRID/entities?layout=field"

Antwort 201 Created; der Pfad des neuen Eintrags steht im Header Location, der Rumpf ist text/plain.

Ein POST ohne Rumpf ist ein Fehler

Ohne Rumpf antwortet das Backend mit 400. Für einen Eintrag ohne Werte schicken Sie ein leeres Werteobjekt im gewählten Layout.

Eintrag ändern

Es gibt kein PATCH auf Einträgen, sondern zwei Wege:

# PUT — Layout frei wählbar, Vorgabe field
curl -s -X PUT -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"6512cc…": "Aufgabe überarbeitet"}' \
  "$BASE$GRID/entities/$ENTITY_ID?layout=field"

# POST …/update — Schlüssel dürfen Feld-ID oder Feldschlüssel sein
curl -s -X POST -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"titel": "Aufgabe überarbeitet", "6512dd…": "2026-05-01"}' \
  "$BASE$GRID/entities/$ENTITY_ID/update"

Beide antworten mit 200 und dem Eintrag in seinem neuen Stand.

PUT ersetzt den Eintrag nicht

Bei allen schlüsselbasierten Layouts — field, key, keyAndField, property — schreibt PUT nur die genannten Felder; nicht genannte behalten ihren Wert. Ein Feld leeren Sie, indem Sie es ausdrücklich auf null setzen.

Nur mit ?layout=indexed schreibt PUT tatsächlich alle Felder, weil dieses Layout ohnehin für jedes Feld einen Wert verlangt.

POST …/update ignoriert layout

Der Endpunkt nimmt den Parameter layout entgegen, liest den Rumpf aber immer im Layout keyAndField: Schlüssel dürfen Feld-IDs oder Feldschlüssel sein, gemischt. Ein anderes Layout anzugeben ändert daran nichts.

Eintrag löschen

curl -s -X DELETE -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  "$BASE$GRID/entities/$ENTITY_ID"

Antwort 200 mit dem Rumpf "deleted".

Änderungsverlauf eines Eintrags

curl -s -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  "$BASE$GRID/entities/$ENTITY_ID/events?pageSize=20"

Eine seitenweise Sammlung von Ereignissen: wer wann welchen Wert geändert hat.

Einträge in einer Ansicht

Ein Virtual Grid hat eine eigene Adresse in Gridform. Beides führt zum selben Ergebnis:

# Über die Adresse der Ansicht
curl -s -u "$APPTIVE_KEY:$APPTIVE_SECRET" "$BASE$VIRTUAL_GRID/entities"

# Über das Eltern-Grid
curl -s -u "$APPTIVE_KEY:$APPTIVE_SECRET" "$BASE$GRID/entities?viewId=$VIRTUAL_GRID_ID"

Der zweite Weg ist praktisch, wenn Sie zwischen Ausschnitten wechseln, ohne Pfade zu tauschen.

Filter und Sortierung werden im Gesamtschema aufgelöst

filter und sorting dürfen Felder nennen, die die Ansicht ausblendet — aufgelöst werden sie gegen das Schema des zugrunde liegenden Grids.

Typische Fehler beim Schreiben

Antwort	Ursache
400 „The entity format is not an indexed entity format"	Objekt mit Schlüsseln geschickt, aber layout=indexed ist in Kraft
400 „Number of submitted values … does not match"	indexed mit falscher Anzahl Werte
400 „Unknown field identifier: …"	Schlüssel passt zu keinem Feld des Grids
400 Typfehler	Wert passt nicht zum Feldtyp, etwa Text in einem Zahlenfeld
403	Rolle reicht nicht — Schreiben verlangt writer

→ Fehlerbehandlung