Zum Hauptinhalt springen

Objekte und Datensätze

Objekte definieren die Datensatztypen eines Workspace, zum Beispiel Anlagen, Wartungsanfragen, Standorte, Verträge oder Inspektionen. Tourfold stellt Standard- und Systemobjekte bereit; zusätzlich kann ein Workspace benutzerdefinierte Objekte für geschäftsspezifische Konzepte anlegen. Beide verwenden denselben typisierten Vertrag für Objekte und Datensätze.

Das Modell besteht aus drei Ebenen:

EbeneDefinitionBeispiel
ObjektDatensatztyp und Anzeigenameequipment
AttributTypisiertes Feld des Objektsasset_tag (Text), operational (Boolean)
DatensatzEine Instanz mit AttributwertenRooftop HVAC Unit RTU-17

Ein Objekt ähnelt einer Tabelle, ein Attribut einer typisierten Spalte und ein Datensatz einer Zeile. Darüber hinaus bildet die API lokalisierte Bezeichnungen, Anzeigevorlagen, Auswahlwerte, Statusabläufe, Relationen, Validierung, Berechtigungen und stabile öffentliche Identitäten ab.

REST oder GraphQL wählen​

Die beiden APIs ergänzen einander:

AufgabeAPI
Objekte und Attribute anlegen oder ändernREST
Datensätze anlegen, ändern oder löschenREST
Datensätze auflisten oder strukturiert abfragenREST
Einen verbundenen Datensatzgraphen in einer Anfrage lesenGraphQL
Das für den Workspace generierte GraphQL-Schema herunterladenGraphQL-Schema-Endpoint

GraphQL ist ausschließlich lesend. Seine Typen und Felder werden aus denselben Objektdefinitionen wie bei REST erzeugt. Eine Objektänderung ändert daher auch das GraphQL-Schema des Workspace. Der GraphQL-Leitfaden beschreibt Benennung, Abfragen, Paginierung, Limits und Fehler.

Schnellstart​

Die folgenden Anfragen legen das Objekt equipment und dessen ersten Datensatz an. Alle Beispiele verwenden die öffentliche /api/v2-Oberfläche und ein Bearer-Token.

1. Objekt anlegen​

curl -X POST "https://api.tourfold.com/api/v2/definitions/objects" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"slug": "equipment",
"name": {
"en": { "singular": "Equipment item", "plural": "Equipment" },
"de": { "singular": "Anlage", "plural": "Anlagen" }
},
"display_template": "{{name}} ({{asset_tag}})",
"attributes": [
{
"slug": "name",
"type": "text",
"name": { "en": "Name", "de": "Name" },
"config": { "is_required": true }
},
{
"slug": "asset_tag",
"type": "text",
"name": { "en": "Asset tag", "de": "Anlagenkennzeichen" },
"config": { "is_required": true, "is_unique": true }
},
{
"slug": "operational",
"type": "boolean",
"name": { "en": "Operational", "de": "Betriebsbereit" },
"config": { "default": true }
}
]
}'

Die Antwort lautet 201 Created und enthält das kanonische Objekt. Tourfold vergibt unveränderliche UUIDs für Objekt und Attribute, ergänzt die vier Systemattribute und liefert lock_version für weitere Schemaänderungen.

OpenAPI: createObject

2. Datensatz anlegen​

curl -X POST "https://api.tourfold.com/api/v2/objects/equipment/records" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"data": {
"name": "Rooftop HVAC Unit RTU-17",
"asset_tag": "AFS-RTU-17",
"operational": true
}
}'

Die Antwort trennt Systemmetadaten von den eigenen Daten:

{
"id": "6f3d2a10-0000-4000-8000-000000000117",
"created_at": "2026-08-26T09:30:00Z",
"updated_at": "2026-08-26T09:30:00Z",
"lock_version": 0,
"data": {
"name": "Rooftop HVAC Unit RTU-17",
"asset_tag": "AFS-RTU-17",
"operational": true
}
}

OpenAPI: createRecord

3. Mit GraphQL lesen​

Nach dem Herunterladen des Workspace-Schemas kann dasselbe Objekt über das aus dem Slug abgeleitete Wurzelfeld abgefragt werden:

query EquipmentByAssetTag {
equipment(where: { asset_tag: { _eq: "AFS-RTU-17" } }, first: 1) {
edges {
node {
id
name
asset_tag
operational
}
}
}
}

Identität und sichere Umbenennungen​

Objekte und Attribute besitzen eine unveränderliche, vom Server vergebene id und einen veränderlichen slug. Auswahlwerte und Status verwenden entsprechend eine unveränderliche id und einen veränderlichen value.

Slugs eignen sich für lesbare, interaktive Aufrufe. Dauerhafte Integrationen sollten UUIDs speichern und bei deklarativen Schemaänderungen bestehende UUIDs mitsenden. Dadurch kann ein Slug oder Auswahlwert umbenannt werden, ohne eine neue Ressource anzulegen oder Relationen zu beschädigen.

Berechtigungen​

Objekte und Datensätze verwenden sowohl Grants als auch objektbezogene Zugriffskontrolle:

GrantErlaubt
objects:configuration:readObjektkatalog und Definitionen lesen
objects:configuration:createObjekte anlegen
objects:configuration:updateObjektschemas ändern oder löschen
objects:configuration:edit-permissionsDie Berechtigungsmatrix eines geschützten Objekts verwalten, sofern der Aufrufer nicht dessen Besitzer ist
objects:records:readDatensätze über REST und GraphQL lesen
objects:records:createDatensätze anlegen
objects:records:updateDatensätze ändern
objects:records:deleteDatensätze löschen

Objektdefinitionen bleiben als Tenant-Metadaten sichtbar; nicht zugängliche Objekte werden nicht still aus dem Katalog entfernt. Beschreibbare Objekte (is_readonly: false) besitzen eine eigene Berechtigungsmatrix. Einträge gelten für alle, für eine Rolle oder für einen Benutzer und vergeben read oder write. manage ergibt sich aus Besitz oder Verwaltungsbefugnis und kann in der Matrix nicht vergeben werden. Schreibgeschützte Systemobjekte (is_readonly: true) werden über Grants gesteuert und besitzen keine bearbeitbare Matrix.

Berechtigungsmatrizen sind vollständige Mengen: PUT {"entries": [...]} ersetzt die gesamte Matrix, {"entries": []} leert sie. Lesen oder Ändern erfordert den Definitions-Lesegrant und zusätzlich den Edit-Permissions-Grant oder den Besitz des Objekts. Dafür dienen getObjectPermissions und updateObjectPermissions.

Eine verweigerte REST-Datensatzanfrage liefert 403 access-denied mit data.reason = "not_member". GraphQL behält das Feld im generierten Schema und meldet einen expliziten Feldfehler statt einer leeren Connection.

Nächste Schritte​

  • Objekte und Attribute: Identität, Lokalisierung, Schemaänderungen und alle Attributtypen.
  • Datensätze: CRUD, Wertformen, Filterung, Sortierung, Batch-Schreibvorgänge und optimistisches Locking.
  • Relationen: Zielobjekte, verwaltete Rückseiten, Kardinalität und Navigation.
  • Attribut-Leitfaden: Typen anhand ihres Validierungs-, Abfrage- und Integrationsverhaltens auswählen.
  • Integrationsleitfäden: Schemas weiterentwickeln und Datensätze sicher synchronisieren.
  • GraphQL: Workspace-Schemas und verbundene Lesezugriffe.
  • Fehler: RFC-9457-Problemdokumente und feldgenaue Pointer.