Die REST-API im Überblick

Alles, was die ApptiveGrid-Oberfläche kann, geht über dieselbe öffentliche HTTP-API: Spaces anlegen, Grids lesen, Einträge schreiben, Ansichten und Formulare verwalten. Diese Seiten beschreiben sie aus der Sicht einer Anwendung, die von außen zugreift.

Basisadresse	https://app.apptivegrid.de
Präfix aller Endpunkte	/api
Format	JSON (application/json)
Anmeldung	API-Schlüssel oder Bearer-Token → Authentifizierung
Maschinenlesbare Beschreibung	openapi.json (OpenAPI 3.1)

Die API ist selbstbeschreibend

Jede Antwort trägt ein Feld _links. Darin stehen die Operationen, die die aufrufende Identität auf genau dieser Ressource ausführen darf — mit Pfad und HTTP-Methode:

{
  "_representation": "full",
  "id": "6489…",
  "name": "Projekte",
  "_links": {
    "self":      { "href": "/api/users/64…/spaces/64…/grids/64…", "method": "get" },
    "entities":  { "href": "/api/users/64…/spaces/64…/grids/64…/entities", "method": "get" },
    "addEntity": { "href": "/api/users/64…/spaces/64…/grids/64…/entities", "method": "post" },
    "schema":    { "href": "/api/users/64…/spaces/64…/grids/64…/schema", "method": "get" }
  }
}

Daraus folgen zwei Gewohnheiten, die Integrationen langlebig machen:

Pfade folgen, nicht bauen

Lesen Sie den nächsten Pfad aus _links, statt ihn aus IDs zusammenzusetzen. Das Backend entscheidet, wie eine Adresse aussieht; wer _links folgt, bleibt von Umstellungen unberührt. Abgelöste Adressen bleiben als veraltete Routen erreichbar.

_links ist zugleich die Rechteauskunft

Fehlt addEntity, darf die aktuelle Identität in diesem Grid keine Einträge anlegen. Sie müssen Berechtigungen nicht raten und keinen Fehlversuch provozieren.

Neben _links können Antworten _embedded enthalten: mitgelieferte Untersammlungen, damit für den ersten Bildschirm nicht zehn Anfragen nötig sind.

Die Ressourcen und wie sie ineinanderliegen

Benutzer  /api/users/{userId}
└── Space                     /spaces/{spaceId}
    ├── Grid                  /grids/{gridId}
    │   ├── Eintrag           /entities/{entityId}
    │   ├── Feld              /fields/{fieldId}
    │   ├── Formular          /forms/{form}
    │   ├── Ansicht (Daten)   /virtualgrids/{gridId}
    │   └── Ansicht (Anzeige) /sviews/{sview}
    ├── Seite / Block         /blocks/{blockId}
    ├── Freigabe              /shares/{share}
    └── Öffentlicher Link     /externalHooks/{externalHookInternalId}

Begriff	In der API	Bedeutung
Space	spaces	Behälter für Grids, Seiten und Freigaben
Grid	grids	Tabelle mit Feldern und Einträgen
Eintrag	entities	Eine Zeile
Feld	fields	Eine Spalte samt Typ
Virtual Grid	virtualgrids	Datenausschnitt eines Grids: Feldauswahl, Filter, Sortierung
Stateful View	sviews	Darstellung eines Ausschnitts, etwa als Kanban oder Kalender
Formular	forms	Erfassungsmaske für ein Grid
Block	blocks	Baustein einer Seite

Zwei Dinge heißen „Ansicht"

virtualgrids bestimmt welche Daten, sviews bestimmt wie sie aussehen.

Ein Virtual Grid bekommt eine Adresse in derselben Form wie ein Grid — /api/users/{userId}/spaces/{spaceId}/grids/{virtualGridId} — und ist über dieselben Endpunkte lesbar, /entities eingeschlossen. Alternativ liest man den Ausschnitt am Eltern-Grid mit ?viewId={virtualGridId}.

Was diese API nicht ist

Ein paar Erwartungen, die die API bewusst nicht erfüllt:

• Kein festes Eintragsschema. Welche Schlüssel ein Eintrag hat, hängt vom Grid und vom gewählten Layout ab. → Einträge
• Keine Gesamtliste aller Spaces im System. Alles hängt unterhalb einer Benutzerkennung.
• Kein PATCH auf Einträgen. Teilaktualisierungen laufen über POST …/entities/{entityId}/update.

Versionierung der Darstellung

Der Accept-Header wählt aus, welche Darstellung das Backend liefert:

Accept: application/vnd.apptivegrid.hal;version=2

Ohne Angabe antwortet das Backend mit der Standarddarstellung der jeweiligen Ressource. Für Grids und Virtual Grids lohnt sich version=2: nur dort liefert die Antwort die vollständigen Felddefinitionen unter fields mit.

Die Antwort selbst trägt immer Content-Type: application/json.

Woher diese Dokumentation stammt

Endpunkte, Parameter, Berechtigungen und Statuscodes sind aus dem Backend ausgelesen, nicht von Hand gepflegt. → Endpunkt-Referenz