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:
| Ebene | Definition | Beispiel |
|---|---|---|
| Objekt | Datensatztyp und Anzeigename | equipment |
| Attribut | Typisiertes Feld des Objekts | asset_tag (Text), operational (Boolean) |
| Datensatz | Eine Instanz mit Attributwerten | Rooftop 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:
| Aufgabe | API |
|---|---|
| Objekte und Attribute anlegen oder ändern | REST |
| Datensätze anlegen, ändern oder löschen | REST |
| Datensätze auflisten oder strukturiert abfragen | REST |
| Einen verbundenen Datensatzgraphen in einer Anfrage lesen | GraphQL |
| Das für den Workspace generierte GraphQL-Schema herunterladen | GraphQL-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:
| Grant | Erlaubt |
|---|---|
objects:configuration:read | Objektkatalog und Definitionen lesen |
objects:configuration:create | Objekte anlegen |
objects:configuration:update | Objektschemas ändern oder löschen |
objects:configuration:edit-permissions | Die Berechtigungsmatrix eines geschützten Objekts verwalten, sofern der Aufrufer nicht dessen Besitzer ist |
objects:records:read | Datensätze über REST und GraphQL lesen |
objects:records:create | Datensätze anlegen |
objects:records:update | Datensätze ändern |
objects:records:delete | Datensä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.