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. Der Wert ist eine Liste benannter einbettbarer Ressourcen, und welche Namen gültig sind, wird pro Endpoint festgelegt und in der OpenAPI-Spezifikation dokumentiert — es gibt keinen universellen Include-Katalog. Verfügbar ist es auf ausgewählten Lese-Endpoints, nicht auf allen.

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: Relationen von Custom Objects

Custom-Object-Instanzen enthalten ihre eigenen dynamischen Eigenschaften unter data; zugehörige Instanzen werden nicht als erfundene Beziehungsattribute eingebettet. Lesen Sie eine Equipment-Instanz mit ihrem Definitions-Slug und ihrer Instanz-ID:

curl "https://api.tourfold.com/api/v2/custom-objects/instances/equipment/6f3d2a10-0000-4000-8000-000000000101" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "slug": "equipment",
    "title": "Equipment",
    "type": "object"
  },
  "data": {
    "id": "6f3d2a10-0000-4000-8000-000000000101",
    "created_at": "2026-03-01T08:00:00Z",
    "updated_at": "2026-03-01T08:00:00Z",
    "name": "Rooftop Unit RTU-17",
    "asset_tag": "AFS-RTU-17",
    "operational": true
  },
  "display_value": "Rooftop Unit RTU-17",
  "lock_version": 0
}

Um die zugehörigen Wartungsanfragen zu lesen, verwenden Sie den in der Custom-Object-Relation deklarierten Relations-Slug:

curl "https://api.tourfold.com/api/v2/custom-objects/instances/equipment/6f3d2a10-0000-4000-8000-000000000101/associated/maintenance_requests" \
  -H "Authorization: Bearer YOUR_TOKEN"

Die Antwort verwendet den üblichen Custom-Object-Umschlag aus items, schema und page. Zum Filtern, Sortieren, Paginieren oder Durchlaufen mehrerer Custom-Object-Relationen in einem Lesezugriff verwenden Sie die schreibgeschützte GraphQL-API.

URLs verschachtelter Ressourcen

Verwandte Sammlungen sind auch direkt adressierbar. Reale Beispiele:

# Wartungsanfragen zu einer Equipment-Instanz
GET /api/v2/custom-objects/instances/equipment/{instance_id}/associated/maintenance_requests

# 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 Custom-Object-Endpoint für zugehörige Instanzen verwendet denselben Umschlag für die vollständige Ergebnismenge. Siehe Paginierung, Sortierung & Filterung.

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 Custom-Object-Instanzen 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"
}