Zum Hauptinhalt springen

Verwandte Ressourcen

Es gibt zwei Wege, mit Daten zu arbeiten, die zu einer Ressource gehören:

  1. In die Antwort einbetten mit dem Query-Parameter ?include= — gut, um verwandte Daten gemeinsam mit der übergeordneten Ressource in einer Anfrage zu lesen.
  2. Ü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.

DarstellungInhalt von items
Eingebettete kompakte Ansichtrecord_id, object, display_name
Eingebettete erweiterte AnsichtDieselben kompakten Felder plus record mit dem kanonischen Datensatz
Endpoint für verknüpfte DatensätzeKanonische 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"
}