Verwandte Ressourcen
Es gibt zwei Wege, mit Daten zu arbeiten, die zu einer Ressource gehören:
- In die Antwort einbetten mit dem Query-Parameter
?include=— gut, um verwandte Daten gemeinsam mit der übergeordneten Ressource in einer Anfrage zu lesen. - Über eine verschachtelte URL zugreifen — gut, um mit der Beziehung zu arbeiten oder durch eine große verwandte Sammlung zu paginieren.
Tourfold verwendet keinen JSON:API-artigen relationships/included-Umschlag. Eingebettete
Daten werden inline in der Ressource abgelegt, zu der sie gehören.
Verwandte Daten mit ?include= einbetten
?include= ist opt-in: Verwandte Daten sind nur vorhanden, wenn Sie sie anfordern. Wiederholen Sie
den Parameter für jede benannte einzubettende Ressource; senden Sie keine kommagetrennte Liste:
GET /api/v2/objects/equipment/records?include=manufacturer&include=maintenance_requests
Welche Namen gültig sind, wird pro Endpoint festgelegt und in der
OpenAPI-Spezifikation dokumentiert — es gibt keinen universellen
Include-Katalog. Verfügbar ist include auf ausgewählten Lese-Endpoints, nicht auf allen. Ein
unbekannter oder nicht erweiterbarer Name liefert einen feldbezogenen 422-Fehler mit dem Pointer
#/include.
Beispiel: aktueller Gerätezustand
GET /api/v2/devices/{device_id} und GET /api/v2/devices akzeptieren ?include=current_state. Der
materialisierte Zustand wird als Feld current_state am Gerät eingebettet und ist nur vorhanden, wenn
er angefordert wird:
curl "https://api.tourfold.com/api/v2/devices/a1b2c3d4-e5f6-4a1b-8c9d-123456789abc?include=current_state" \
-H "Authorization: Bearer YOUR_TOKEN"
{
"id": "a1b2c3d4-e5f6-4a1b-8c9d-123456789abc",
"kind": "TOURFOLD_APP",
"device_model": "iPhone 15",
"provisioning_state": "PROVISIONED",
"lock_version": 3,
"current_state": {
"last_received_at": "2024-01-15T10:29:00Z",
"location": { "latitude": 48.2038, "longitude": 16.3698 }
}
}
Ohne ?include=current_state fehlt das Feld current_state schlicht.
Beispiel: Objektrelationen
Objektdatensätze enthalten die im Workspace definierten Attribute unter data. Lesen Sie
Alpines Datensatz RTU-17 mit dem Objekt-Slug (oder der Objekt-UUID) und der Datensatz-ID:
curl "https://api.tourfold.com/api/v2/objects/equipment/records/6f3d2a10-0000-4000-8000-000000000101" \
-H "Authorization: Bearer YOUR_TOKEN"
{
"id": "6f3d2a10-0000-4000-8000-000000000101",
"display_name": "Rooftop HVAC Unit RTU-17 (AFS-RTU-17)",
"created_at": "2026-03-01T08:00:00Z",
"updated_at": "2026-03-01T08:00:00Z",
"lock_version": 0,
"data": {
"name": "Rooftop HVAC Unit RTU-17",
"asset_tag": "AFS-RTU-17",
"operational": false,
"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
}
}
}
}
?include=maintenance_requests erweitert diese benannte Beziehung inline. Jeder kompakte Zeiger erhält
ein Feld record, das denselben kanonischen Datensatz-Envelope wie ein direkter Datensatzabruf enthält.
Unbekannte Include-Namen liefern 422; ohne Include bleiben die kompakten Zeiger
{record_id, object, display_name} erhalten.
Die Erweiterung umfasst genau eine Ebene. Relationen innerhalb des erweiterten record bleiben
kompakte Referenzen; der Server folgt ihnen nicht rekursiv und erweitert keine Zyklen implizit.
Fordern Sie jede Relation an der Ressource an, zu der sie gehört, oder verwenden Sie GraphQL für eine
gezielt verschachtelte Auswahl.
To-many-Beziehungen enthalten höchstens 50 kompakte Ansichten unter items. Ihr verschachteltes
page gibt die vollständige Gesamtzahl an. Ist page.total_elements größer als items.length,
laden Sie weitere Datensätze über den Related-Endpoint. Leere Beziehungen haben items: [] und
Gesamtzahlen von null.
Um die Wartungsanfragen von RTU-17 unabhängig zu paginieren, verwenden Sie den Attribut-Slug der Beziehung:
curl "https://api.tourfold.com/api/v2/objects/equipment/records/6f3d2a10-0000-4000-8000-000000000101/related/maintenance_requests?page=0&size=20" \
-H "Authorization: Bearer YOUR_TOKEN"
Die Antwort verwendet den üblichen Datensatzlisten-Umschlag {items, page}. Verwenden Sie
POST …/records/{record_id}/related/{attribute_ref}/query, um innerhalb dieser verknüpften Sammlung zu
filtern und zu sortieren, POST /api/v2/objects/{object_ref}/records/query für die Sammlung auf oberster
Ebene oder die schreibgeschützte GraphQL-API, um mehrere Beziehungen in einem
Lesezugriff zu durchlaufen.
Eine Objektbeziehung definieren
Ein Beziehungsattribut hat genau ein festes Ziel. Verwenden Sie das singuläre Feld config.target mit
einem Objekt-Slug oder einer UUID; polymorphe Felder allowed_object oder allowed_objects gibt es
nicht:
{
"slug": "manufacturer",
"type": "relationship",
"name": { "de": "Hersteller" },
"config": {
"target": "manufacturer",
"is_multiselect": false,
"reverse": {
"slug": "assets",
"name": { "de": "Anlagen" },
"is_multiselect": true
}
}
}
Das Objekt, das die Beziehung deklariert, besitzt deren Schema. Ein optionales reverse materialisiert
am Zielobjekt ein zweites Attribut mit is_system_managed: true und einem config.target, das zurück
zum Besitzer zeigt. Datensatzverknüpfungen können nur über das besitzende Attribut geschrieben werden;
die verwaltete Rückseite kann weder geschrieben noch direkt umbenannt, aktualisiert oder gelöscht werden. Ihr slug
muss am Zielobjekt frei sein: Er darf weder ein eigenes Zielattribut noch ein anderes Beziehungsfeld oder
eine weitere im selben Request deklarierte Rückseite überschreiben. Eine Kollision liefert 422 mit
einem Feldfehler am Rückseiten-Slug.
PUT /definitions/objects/{definition_ref} ersetzt die Attribute, die diesem Objekt gehören. Wird eine eigene
Beziehung auf der A-Seite ausgelassen, werden die Beziehung und ihre Rückseite gelöscht. Wird die
verwaltete Rückseite in einem PUT der B-Seite ausgelassen, bleibt sie erhalten; wird sie gesendet oder
direkt verändert, folgt 422 mit dem Feldfehlertyp relationship-reverse-managed.
URLs verschachtelter Ressourcen
include verändert die Darstellung der aktuellen Ressource; es ist selbst keine Subressource.
Verwandte Sammlungen sind über eigene verschachtelte URLs adressierbar. Reale Beispiele:
# Wartungsanfragen zu einer Equipment-Instanz
GET /api/v2/objects/equipment/records/{record_id}/related/maintenance_requests
POST /api/v2/objects/equipment/records/{record_id}/related/maintenance_requests/query
# Die Fähigkeiten eines Benutzers (ganze Menge; PUT-Semantik siehe Ressourcen erstellen & aktualisieren)
GET /api/v2/users/{user_id}/skills
PUT /api/v2/users/{user_id}/skills
# Die Tags eines Benutzers
GET /api/v2/users/{user_id}/tags
Form und Paginierungsmöglichkeiten einer Sammlung werden je Operation deklariert. Paginierte
Sammlungen folgen dem üblichen items- + page-Umschlag; der Endpoint für zugehörige Datensätze
verwendet denselben Umschlag für die vollständige Ergebnismenge. Siehe
Paginierung, Sortierung & Filterung.
Eingebettete Beziehungsseiten
Der konfigurierte Beziehungsname, etwa service_sites, bleibt erhalten. Die Sammlung verwendet
{items, page}. Eine kompakte Referenz ist ein Eintragsmodell: eine Ansicht mit Identitäts- und
Anzeigefeldern. Das Eintragsschema beschreibt den Inhalt; der Umschlag bleibt auch dann gleich,
wenn weitere Felder eingebettet werden.
| Darstellung | Inhalt von items |
|---|---|
| Eingebettete kompakte Ansicht | record_id, object, display_name |
| Eingebettete erweiterte Ansicht | Dieselben kompakten Felder plus record mit dem kanonischen Datensatz |
| Endpoint für verknüpfte Datensätze | Kanonische verknüpfte Datensätze in den dokumentierten Umschlägen {kind, definition_id, record} |
Die kompakte Darstellung sieht beispielsweise so aus:
{
"data": {
"service_sites": {
"items": [
{
"record_id": "6e606af6-71d5-4751-bdee-acc7c452f559",
"object": "service_sites",
"display_name": "Lager Wien"
}
],
"page": {
"size": 50,
"total_elements": 1,
"total_pages": 1,
"number": 0
}
}
}
}
Eine leere Sammlung verwendet items: []. Führen Sie weder refs noch eine Umbenennung in
service_site_refs oder einen Diskriminator allein zur Kennzeichnung einer kompakten Ansicht ein.
Definitionen, Lese- und Schreibzugriffe, Filter und include verwenden weiterhin den konfigurierten
Attribut-Slug. To-one-Beziehungen liefern ein einzelnes Referenzobjekt oder ausdrücklich null, wenn sie
nicht gesetzt sind, ohne Seitenumschlag. Nicht lesbare Beziehungen werden weggelassen; null
kennzeichnet daher ein lesbares Feld ohne Verknüpfung.
Verwenden Sie die üblichen Paginierungsfelder.
size ist die Seitenkapazität, number beginnt bei null, und die Gesamtwerte beziehen sich auf die
vollständige verknüpfte Menge, die für den Aufrufer lesbar ist. Eine leere Menge hat
total_elements: 0 und total_pages: 0. Jede Beziehung hat eine eigene Seite, unabhängig von der
Seite der übergeordneten Datensatzliste. Die Gesamtzahlen stammen aus der vollständigen Menge,
nicht aus der Vorschau. Das verschachtelte page ersetzt das frühere separate relationship_page_info.
include=service_sites bleibt dort, wo es unterstützt wird, eine additive Erweiterung: Jeder
Eintrag unter items behält seine kompakten Felder und erhält einen record mit der vollständigen
kanonischen Antwort. Der kompakte Eintrag ist damit eine Teilmenge des erweiterten Eintrags.
Die Erweiterung umfasst weiterhin eine Ebene.
Bestehende Endpoints für verknüpfte Datensätze liefern bereits {items, page} mit typisierten
Einträgen der Form {kind, definition_id, record}; diese Umschläge bleiben Teil ihres Vertrags.
Schreiben Sie eine einzelne UUID/Referenz für To-one und ein Array für To-many. Optionale
To-one-Felder leeren Sie mit null, To-many-Felder mit []; Weglassen erhält bei PATCH den Wert.
Bestehende To-one-Arrayeingaben bleiben kompatibel, mit höchstens einem Ziel. Der Leseumschlag und die page-Metadaten sind keine Schreibdaten.
Clients dürfen beim Bearbeiten eines anderen Feldes eine abgeschnittene Vorschau nicht als
vollständige Verknüpfungsmenge speichern.
Dies folgt der allgemeinen Konvention für Eintragsdarstellungen:
items kann dokumentierte Zusammenfassungsmodelle, kompakte Ansichten oder vollständige Datensätze
enthalten. Die Umstellung hier betrifft benutzerdefinierte Beziehungsattribute; native Arrays
innerhalb von Aggregaten wie linked_records bei Aufgaben werden dadurch nicht automatisch zu
paginierten Sammlungen.
Wann einbetten vs. verschachtelte URL verwenden
Verwenden Sie ?include=, wenn:
- Sie etwas verwandte Daten zur Anzeige gemeinsam mit der übergeordneten Ressource benötigen.
- Sie einen zweiten Roundtrip vermeiden möchten.
Verwenden Sie die verschachtelte URL, wenn:
- Sie durch eine große verwandte Sammlung paginieren müssen.
- Sie mit der Beziehung arbeiten möchten (die Fähigkeiten eines Benutzers ersetzen, zugehörige Objektdatensätze auflisten).
Halten Sie ?include=-Listen minimal — jede eingebettete Ressource erhöht Aufwand und Antwortgröße.
Fehlerbehandlung
Fehler sind RFC-9457-Problemdokumente (siehe Fehler):
{
"type": "https://problems.tourfold.com/not-found",
"title": "Resource not found",
"detail": "No record with id 'a1b2c3d4-e5f6-4a1b-8c9d-123456789abc' exists"
}