Datensätze
Ein Datensatz ist eine Instanz eines Objekts. REST übernimmt Schreibvorgänge und strukturierte Abfragen; GraphQL stellt lesende Graphabfragen über dieselben Daten bereit.
Alle Datensatzpfade akzeptieren den Objekt-Slug oder die UUID als {object_ref}.
Datensatz-Envelope
Systemmetadaten stehen auf oberster Ebene, Attributwerte nach Attribut-Slug in data:
{
"id": "6f3d2a10-0000-4000-8000-000000000117",
"definition_id": "11111111-9999-4444-8888-111111111111",
"natural_id": "EQUIPMENT-117",
"display_name": "Rooftop HVAC Unit RTU-17 (AFS-RTU-17)",
"created_at": "2026-08-26T09:30:00Z",
"updated_at": "2026-08-26T10:15:00Z",
"lock_version": 1,
"data": {
"name": "Rooftop HVAC Unit RTU-17",
"asset_tag": "AFS-RTU-17",
"operational": true,
"maintenance_requests": {
"items": [
{
"record_id": "7a4e2b10-0000-4000-8000-000000000201",
"object": "maintenance_request",
"display_name": "Temperatur im dritten Stock zu hoch"
}
],
"page": {
"size": 50,
"total_elements": 1,
"total_pages": 1,
"number": 0
}
}
}
}
definition_id ist die unveränderliche UUID der Objektdefinition. Sie steht in jedem kanonischen
Datensatz-Envelope, auch in Schreibantworten, Listen, Batches und erweiterten verknüpften Datensätzen,
unabhängig davon, ob die Anfrage den Slug oder die UUID der Definition verwendet. Sie bleibt beim
Umbenennen der Definition unverändert.
display_name ist die kanonische, lesbare Bezeichnung des Datensatzes und wird mit demselben Renderer
wie kompakte Relationsreferenzen erzeugt. Eine konfigurierte display_template hat Vorrang. Ohne
Vorlage wählen benutzerdefinierte Objekte automatisch, in dieser Reihenfolge, einen befüllten Namen oder
Titel, einen Vor- und Nachnamen, eine fachliche Referenz (etwa eine Fallnummer oder ein Kennzeichen),
einen eindeutigen Textwert oder bis zu zwei kurze Textwerte. E-Mail- und Telefonfelder sind ein letzter
wertbasierter Rückfall. Leere Werte, UUID-Werte, Beschreibungen, Booleans, Datumswerte, Auswahl-IDs und
Relationen werden nicht zu automatischen Bezeichnungen. Allgemeiner Text muss einzeilig sein und darf
höchstens 80 Zeichen lang sein; die vollständige automatische Bezeichnung ist auf 120 Zeichen begrenzt.
Gibt es keinen verwendbaren Wert oder wird eine manuelle Vorlage leer gerendert, verwenden
benutzerdefinierte Objekte ihre aktuelle Natural ID, zum Beispiel
EQUIPMENT-117. Integrierte Objekte behalten ihren bisherigen Rückfall auf Vorlage bzw. UUID.
Bezeichnungen werden aus den aktuellen Daten und Attributen aufgelöst; eine erzeugte Vorlage wird nicht
gespeichert. Eine gesetzte Vorlage ersetzt die automatische Benennung; wird sie geleert, gilt wieder die
automatische Benennung. Bezeichnungen sind keine eindeutigen Kennungen. Clients sollten display_name
für Listenzeilen, Überschriften, Breadcrumbs und Auswahlfelder verwenden und für die Identität weiterhin
die vollständige id nutzen.
Nicht gesetzte optionale Attribute werden aus data ausgelassen. Systemfelder setzt der Server; sie
dürfen nicht in data geschrieben werden.
To-many-Beziehungen verwenden {items, page} unter ihrem Attribut-Slug. items enthält höchstens
50 kompakte Datensatzansichten; page gibt die vollständige lesbare Gesamtmenge an. Eine leere
Beziehung hat items: [], total_elements: 0 und total_pages: 0. Wenn total_elements größer als
die Anzahl der Einträge ist, laden Sie die weiteren Datensätze über den Related-Endpoint.
To-one-Beziehungen liefern ein kompaktes Referenzobjekt oder ausdrücklich null, wenn sie nicht
gesetzt sind. Nicht lesbare Beziehungen werden weggelassen.
Anlegen
POST /api/v2/objects/equipment/records
Content-Type: application/json
{
"data": {
"name": "Rooftop HVAC Unit RTU-17",
"asset_tag": "AFS-RTU-17",
"operational": true
}
}
Die Antwort ist 201 Created mit Location-Header und kanonischem Datensatz.
Datensatz-Schreibvorgänge sind strikt. Jeder Schlüssel in data muss ein Attribut des Objekts
bezeichnen; unbekannte Schlüssel liefern 422 Validation failed mit einem Unter-Problem
unknown-attribute und einem Pointer wie #/data/misspelled. Sind mehrere Schlüssel ungültig, meldet
die Antwort alle gemeinsam.
OpenAPI: createRecord
Änderung mit JSON Merge Patch
PATCH verwendet JSON Merge Patch (RFC 7386):
- Ein ausgelassenes Attribut bleibt unverändert.
- Ein mitgesendeter Wert ersetzt den aktuellen Wert.
nullleert ein optionales Attribut.- Arrays werden ersetzt und nicht erweitert.
- Eine optionale
lock_versionauf oberster Ebene aktiviert optimistisches Locking.
PATCH /api/v2/objects/equipment/records/6f3d2a10-0000-4000-8000-000000000117
Content-Type: application/merge-patch+json
{
"lock_version": 1,
"data": {
"operational": false
}
}
Eine veraltete mitgesendete Version liefert 409 Conflict. Ohne lock_version wird die
Nebenläufigkeitsprüfung übersprungen und die aktuelle Version geändert.
Bei Mehrfachauswahlen und vom Besitzer deklarierten Relationsattributen ersetzt das Array die
vollständige Menge. [] oder null leert sie; ein ausgelassenes Attribut bleibt unverändert. Eine
materialisierte Relationsrückseite ist schreibgeschützt und liefert 422 relationship-reverse-managed,
wenn sie in den Datensatzdaten enthalten ist.
Ein raw_json-Dokument ist ein einzelner Attributwert. Ein mitgesendetes Dokument ersetzt das
gespeicherte Dokument vollständig, einschließlich verschachtelter Objekte; der Patch führt nie eine
Zusammenführung mit dem gespeicherten Dokument durch. {} und [] sind gespeicherte Dokumente, keine
Löschungen. Nur ein null auf oberster Ebene leert das Attribut. Siehe
Rohe JSON-Dokumente.
Ein rich_text-Wert wird vor dem Speichern normalisiert, und ein Dokument ohne Textinhalt, etwa
<p><br></p>, leert das Attribut wie null. Siehe Formatierter Text.
full_name- und links-Werte sind jeweils ein Attributwert: Ein mitgesendetes Objekt ersetzt das
gespeicherte Objekt vollständig, sodass ein Client, der ein Element ändert, die gesamte Struktur
sendet. Ein Objekt ohne Inhalt, etwa {} oder {"alternatives": []}, leert das Attribut wie
null. Siehe Vollständiger Name und Links.
OpenAPI: updateRecord
Wertformen
Skalare Werte werden in derselben Form zurückgegeben, mit folgenden Regeln für Referenzen:
| Attribut | Schreiben | Lesen |
|---|---|---|
Einfaches select | Options-UUID oder aktueller value | Options-UUID |
Mehrfach-select | Array aus Options-UUIDs/aktuellen Werten | Array aus Options-UUIDs |
state | Status-UUID oder aktueller value | Status-UUID |
tags | Array aus UUIDs, Bezeichnungen oder Referenzobjekten | Array aus {id, label, color} |
required_skills / provided_skills | Array aus UUIDs, Bezeichnungen oder Referenzobjekten | Array aus {id, label} |
Besitzende relationship | Array aus Datensatz-UUIDs oder {record_id} | Array aus {record_id, object, display_name} |
| Verwaltete Relationsrückseite | Nicht schreibbar | Array aus {record_id, object, display_name} |
location | Adresse, Koordinaten oder Tracking-Objekt | Gespeicherte Struktur mit verfügbaren Positionsdaten |
raw_json | Beliebiges JSON-Objekt, -Array, -String, -Zahl oder -Boolean | Dasselbe Dokument als JSON; Schlüsselreihenfolge und Zahlenformat werden normalisiert |
rich_text | HTML-Fragment in der unterstützten Teilmenge oder reiner Text | Kanonischer normalisierter HTML-String |
full_name | {title?, first_name?, last_name?} mit mindestens einem Namensbestandteil | Dasselbe Objekt mit getrimmten Elementen; leere Elemente entfallen |
links | {primary: {url, label?}, alternatives?: [{url, label?}]} | Dasselbe Objekt mit getrimmten Elementen und immer vorhandenem alternatives |
Auch eine einwertige Relation verwendet ein Array; is_multiselect: false begrenzt es auf null oder
einen Eintrag. Beim Lesen aufgelöste Referenzen sind gültige Schreibwerte und können über ein
besitzendes Relationsattribut unverändert zurückgesendet werden. Rückseitenprojektionen müssen über ihre
Besitzerseite geändert werden.
Auflisten
GET /objects/{object_ref}/records akzeptiert ausschließlich:
| Parameter | Bedeutung |
|---|---|
page | Nullbasierte Seitennummer |
size | Seitengröße |
sort | Wiederholbares attribute:asc / attribute:desc oder ein To-one-Sprung wie manufacturer.name:asc |
include | Wiederholbares Referenzattribut zum Erweitern |
search | Wörtliche Teilzeichenfolge des kanonischen display_name, ohne Unterscheidung von Groß- und Kleinschreibung (höchstens 256 Zeichen) |
curl -G "https://api.tourfold.com/api/v2/objects/equipment/records" \
-H "Authorization: Bearer YOUR_TOKEN" \
--data-urlencode "sort=name:asc" \
--data-urlencode "page=0" \
--data-urlencode "size=20"
Die Antwort verwendet den Standard-Envelope { "items": [...], "page": {...} }. Unbekannte
Query-Parameter liefern 422; dynamische Datensatzfilter gehören in den Query-Endpoint.
search wird mit den normalen Datensatzberechtigungen angewendet, bevor Gesamtzahl und Seite der
Treffer berechnet werden. Äußere Leerzeichen werden entfernt; eine leere oder nur aus Leerzeichen
bestehende Suche liefert 422 mit einem Fehler field-required. Für eine ungefilterte Liste lassen Sie
search weg. % und _ sind wörtliche Zeichen, keine Platzhalter. Dieselbe optionale Eigenschaft
search unterstützt auch der Body der strukturierten Abfrage, wo sie per UND mit filter verknüpft
wird; die MCP-Werkzeuge records_list und records_query verhalten sich ebenso.
Gesucht wird in der gewöhnlichen, nicht erweiterten Datensatzdarstellung, einschließlich der aktuellen
Referenzbezeichnungen und des oben beschriebenen automatischen Rückfalls bzw. des Rückfalls für leere
Datensätze. include ergänzt Daten verknüpfter Datensätze, ohne den durchsuchbaren Namen zu ändern.
Automatische Namen und komplexe Vorlagen erfordern unter Umständen, dass Kandidatendatensätze
serverseitig in begrenzten Batches gerendert werden; der Aufwand wächst mit der Kandidatenmenge. Die
Ausführungsfrist beträgt standardmäßig 10 Sekunden. Läuft sie ab, liefert die gesamte Abfrage
503 records/query-timeout, nie Teilergebnisse für die Gesamtzahl. Grenzen Sie eine große
Kandidatenmenge nach Möglichkeit mit einem strukturierten Attributfilter ein.
OpenAPI: listRecords
Strukturierte Abfrage
POST /objects/{object_ref}/records/query dient für Attributfilter, boolesche Verknüpfung, Sortierung und
Paginierung:
{
"filter": {
"operational": { "eq": true },
"or": [
{ "category": { "in": ["hvac", "ventilation"] } },
{ "replacement_cost": { "gt": 25000 } }
],
"maintenance_requests": {
"priority": { "eq": "urgent" }
}
},
"sort": ["name:asc"],
"page": 0,
"size": 20
}
Schlüssel auf derselben Ebene werden mit UND verbunden. and, or und not erlauben eine explizite
Verknüpfung. Relationsattribute akzeptieren verschachtelte Filter für das Zielobjekt, einschließlich
weiterer Relationen, bis zu vier Filterebenen.
Der Operatorkatalog ist typspezifisch:
| Attribut | REST-Operatoren |
|---|---|
id | eq, ne, in, gt, gte, lt, lte |
text, email, phone | eq, ne, in, contains, starts_with, ends_with, is_null |
numerisch, date, date_time | eq, ne, in, gt, gte, lt, lte, is_null |
boolean | eq, ne, is_null |
einfaches select, state | eq, ne, in, is_null |
mehrfaches select | in (einer davon), contains (alle), is_null |
raw_json | is_null |
rich_text | contains (Nur-Text-Projektion), is_null |
full_name | contains (kombinierte Anzeige), is_null; sortierbar nach Nach-, dann Vorname |
links | contains (Bezeichnungen und URLs), is_null |
| Relationen, Tags, Qualifikationen | Verschachtelter Zielfilter |
location, lock_version | Nicht filterbar |
is_null wird bei erforderlichen Attributen ausgelassen. Die entsprechenden GraphQL-Operatoren tragen
einen führenden Unterstrich, etwa _eq und _starts_with, und haben dieselbe Semantik. Textvergleiche
unterscheiden nicht zwischen Groß- und Kleinschreibung und akzeptieren Klartext statt SQL-Wildcard-Muster.
Ungültige Kombinationen aus Operator und Typ liefern einen feldbezogenen Fehler mit Status 422.
Objektmetadaten geben die exakten Fähigkeiten jedes Attributs über is_sortable und filter_operators
bekannt, sodass ein schemagesteuerter Client diese Tabelle nicht hart codieren muss. Relationsattribute
sind selbst nicht skalar sortierbar, aber ein Sprung über eine To-one-Relation wird unterstützt:
{
"filter": { "manufacturer": { "country": { "name": { "eq": "Austria" } } } },
"sort": ["manufacturer.name:asc"]
}
Eine Sortierung über eine To-many-Relation, über mehr als eine Relation, nach location oder nach
lock_version liefert 422, bevor eine Datenbankabfrage ausgeführt wird.
Bei Relationen zum System-Objekt user steht me in id-Filtern für den aufrufenden Benutzer, zum
Beispiel {"filter": {"owner": {"id": {"eq": "me"}}}, "sort": ["owner.lastname:asc"]}. Siehe
Workspace-Benutzer als Ziele.
Die Antwort ist paginiert. Für die Fortsetzung wird derselbe POST mit der nächsten Seitennummer wiederholt.
Strukturierte REST-Datensatzabfragen haben eine Ausführungsfrist von zehn Sekunden. Bei Überschreitung
liefert die API 503 mit dem Problemtyp https://problems.tourfold.com/records/query-timeout und
data.timeout_ms. Datenbankzugriffe haben standardmäßig dieselbe Grenze, damit abgebrochene Arbeit nicht
unbegrenzt weiterläuft.
OpenAPI: queryRecords
Abruf über ID oder eindeutigen Wert
Abruf über UUID:
GET /api/v2/objects/equipment/records/{record_id}
Oder über einen fachlichen Schlüssel:
GET /api/v2/objects/equipment/records/by/asset_tag?attribute_value=AFS-RTU-17
Das Suchattribut muss config.is_unique: true besitzen. Ein nicht eindeutiges Attribut liefert 422;
ein fehlender oder leerer attribute_value liefert 422 mit #/attribute_value; ein fehlender Treffer
liefert 404. Übergeben Sie den Wert als Query-Parameter statt als Pfadsegment. So bleiben codierte
Schrägstriche, Frage- und Rautezeichen, Pluszeichen, Leerzeichen und Unicode-Zeichen Nutzdaten.
Attributreferenzen akzeptieren eine UUID oder den aktuellen Slug; UUID-Referenzen überstehen das
Umbenennen von Slugs. Textschlüssel müssen exakt dem gespeicherten Wert entsprechen, einschließlich
Groß- und Kleinschreibung, Leerzeichen und der Schreibweise von Datum bzw. Zeitstempel; verglichen wird
auf Schlüsselgleichheit, nicht chronologisch. Numerische Schlüssel werden als Dezimalzahlen verglichen.
Auswahl- und Statusschlüssel akzeptieren eine Options- bzw. Status-UUID oder ihren aktuellen Wert. Bei
Attributen, die beim Schreiben normalisiert werden, etwa Telefonnummern, verwenden Sie den gespeicherten
kanonischen Wert. Fahrzeugdatensätze bieten
dasselbe Abrufmuster.
Die Web-App stellt denselben Abruf als teilbaren Deep Link bereit, sodass ein externes System einen Datensatz öffnen kann, ohne seine Tourfold-ID zu kennen:
/app/objects/{object_ref}/by/{attribute_ref}?attribute_value={value}
Die Seite löst den Datensatz über diese Operation auf und leitet dann auf die kanonische Seite
/app/objects/{object_ref}/{natural_id} des Datensatzes weiter; Datensatzseiten akzeptieren in diesem
Segment die Natural ID oder die Datensatz-UUID (siehe Natural IDs). Codieren
Sie attribute_value als Query-Parameter genau wie beim API-Aufruf.
OpenAPI: getRecord · getRecordByUniqueAttribute
Referenzen erweitern und paginieren
Wiederholen Sie include beim Datensatzabruf, um benannte Relationen vollständig zu laden; fassen Sie
mehrere Namen nicht zu einem kommagetrennten Wert zusammen:
GET /api/v2/objects/maintenance_request/records/{record_id}?include=equipment&include=assigned_team
Eine erweiterte Referenz erhält ein Feld record mit dem vollständigen kanonischen Datensatz-Envelope:
id, display_name, Zeitstempel, lock_version, data und die eigenen Metadaten zur Vollständigkeit der
Relationsvorschau. Die kompakten Felder record_id, object und display_name bleiben daneben erhalten;
include ist damit eine echte Obermenge der gewöhnlichen Antwort.
Die Erweiterung umfasst genau eine Ebene. Relationen innerhalb des erweiterten record bleiben
kompakte Referenzen und werden weder rekursiv noch durch Zyklen verfolgt. Verwenden Sie GraphQL, wenn
die Antwort eine gezielte mehrstufige Auswahl benötigt.
In data eingebettete Relationswerte sind eine begrenzte Vorschau. Große verbundene Mengen werden über
den paginierten Related-Endpoint geladen:
GET /api/v2/objects/equipment/records/{record_id}/related/maintenance_requests?page=0&size=20
Die Antwort verwendet {items, page} mit stabiler Sortierung nach Datensatz-ID. Jeder Eintrag ist ein
typisierter Umschlag {kind, definition_id, record} mit der vollständigen kanonischen Antwort des
Zieleigentümers. Siehe den Antwortvertrag für Relationen. Fahrzeugziele
unterstützen derzeit nur das paginierte GET. Soll bei einem Objektziel gefiltert oder sortiert werden,
verwenden Sie den zugehörigen Query-Endpoint:
POST /api/v2/objects/equipment/records/{record_id}/related/maintenance_requests/query
Content-Type: application/json
{
"filter": { "status": { "ne": "closed" } },
"sort": ["priority:desc", "created_at:desc"],
"page": 0,
"size": 20
}
Er verwendet dieselben Filter, die Sortierung über einen To-one-Sprung, denselben Seiten-Envelope und dieselbe zehnsekündige Ausführungsfrist wie das Zielobjekt.
OpenAPI: listRelatedRecords · queryRelatedRecords
Atomares Batch-Anlegen
POST /api/v2/records/batch legt 1–100 Datensätze objektübergreifend in einer Transaktion an. Jeder
Eintrag kann einen anfrageinternen key besitzen. Ein Relationswert {"ref": "<key>"} verweist auf
einen Datensatz, der im selben Batch angelegt wird.
{
"items": [
{
"object": "equipment",
"key": "rtu17",
"data": {
"name": "Rooftop HVAC Unit RTU-17",
"asset_tag": "AFS-RTU-17"
}
},
{
"object": "maintenance_request",
"data": {
"title": "Temperatur im dritten Stock zu hoch",
"equipment": [{ "ref": "rtu17" }]
}
}
]
}
Die Operation ist atomar: Ein ungültiger Eintrag oder eine ungültige Relation setzt den vollständigen Batch zurück. Ergebnisse werden in Eingabereihenfolge geliefert.
OpenAPI: batchCreateRecords
Löschen
DELETE /objects/{object_ref}/records/{record_id} liefert 204 No Content. Relationskanten zum
gelöschten Datensatz werden entfernt; die verbundenen Datensätze bleiben erhalten.
OpenAPI: deleteRecord
Fehler
Validierungsfehler verwenden application/problem+json mit Status 422. Feldfehler enthalten einen
JSON Pointer, beispielsweise #/data/asset_tag. Die Seite Fehler beschreibt das
gemeinsame Problemformat.