Zum Hauptinhalt springen

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.
  • null leert ein optionales Attribut.
  • Arrays werden ersetzt und nicht erweitert.
  • Eine optionale lock_version auf 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:

AttributSchreibenLesen
Einfaches selectOptions-UUID oder aktueller valueOptions-UUID
Mehrfach-selectArray aus Options-UUIDs/aktuellen WertenArray aus Options-UUIDs
stateStatus-UUID oder aktueller valueStatus-UUID
tagsArray aus UUIDs, Bezeichnungen oder ReferenzobjektenArray aus {id, label, color}
required_skills / provided_skillsArray aus UUIDs, Bezeichnungen oder ReferenzobjektenArray aus {id, label}
Besitzende relationshipArray aus Datensatz-UUIDs oder {record_id}Array aus {record_id, object, display_name}
Verwaltete RelationsrückseiteNicht schreibbarArray aus {record_id, object, display_name}
locationAdresse, Koordinaten oder Tracking-ObjektGespeicherte Struktur mit verfügbaren Positionsdaten
raw_jsonBeliebiges JSON-Objekt, -Array, -String, -Zahl oder -BooleanDasselbe Dokument als JSON; Schlüsselreihenfolge und Zahlenformat werden normalisiert
rich_textHTML-Fragment in der unterstützten Teilmenge oder reiner TextKanonischer normalisierter HTML-String
full_name{title?, first_name?, last_name?} mit mindestens einem NamensbestandteilDasselbe 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:

ParameterBedeutung
pageNullbasierte Seitennummer
sizeSeitengröße
sortWiederholbares attribute:asc / attribute:desc oder ein To-one-Sprung wie manufacturer.name:asc
includeWiederholbares Referenzattribut zum Erweitern
searchWö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:

AttributREST-Operatoren
ideq, ne, in, gt, gte, lt, lte
text, email, phoneeq, ne, in, contains, starts_with, ends_with, is_null
numerisch, date, date_timeeq, ne, in, gt, gte, lt, lte, is_null
booleaneq, ne, is_null
einfaches select, stateeq, ne, in, is_null
mehrfaches selectin (einer davon), contains (alle), is_null
raw_jsonis_null
rich_textcontains (Nur-Text-Projektion), is_null
full_namecontains (kombinierte Anzeige), is_null; sortierbar nach Nach-, dann Vorname
linkscontains (Bezeichnungen und URLs), is_null
Relationen, Tags, QualifikationenVerschachtelter Zielfilter
location, lock_versionNicht 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.