Étendre les objets

Les objets liés sont des identifiants par défaut

Pour garder les réponses légères, les objets liés sont renvoyés sous forme de simples chaînes d’identifiant plutôt que d’objets complets. Par exemple, le guest d’une réservation n’est que l’identifiant du client :

{
  "object": "reservation",
  "id": "resv_8xKQ2m4Vd0pErJ7sN1aZ9bQ",
  "guest": "gst_3Td9Lp0WqZ",
  "party_size": 4
}

Étendre

Utilisez le paramètre expand pour intégrer un objet lié dans la même réponse. Passez plusieurs relations sous forme de liste séparée par des virgules (?expand=guest,events).

Ce que vous pouvez étendre, par ressource

Ressource	Relations extensibles
reservation	guest, events
guest	(aucune)

Demander une relation inconnue renvoie une erreur 400 nommant expand dans error.param, de sorte qu’une faute de frappe n’expédie jamais silencieusement des données non étendues.

curl "https://api.useservice.app/v1/reservations/resv_8xKQ2m4Vd0pErJ7sN1aZ9bQ?expand=guest" \
  -H "Authorization: Bearer $SERVICE_API_KEY"

Désormais guest est l’objet client complet :

{
  "object": "reservation",
  "id": "resv_8xKQ2m4Vd0pErJ7sN1aZ9bQ",
  "guest": {
    "object": "guest",
    "id": "gst_3Td9Lp0WqZ",
    "first_name": "Marie",
    "last_name": "Dupont",
    "email": "[email protected]"
  },
  "party_size": 4
}

Étendre les événements

Le flux d’activité du cycle de vie d’une réservation est disponible en ligne avec expand=events. Sans lui, la clé events est absente ; avec lui, vous obtenez les mêmes objets d’événement que le point de terminaison dédié aux événements, dans l’ordre chronologique — ainsi un ETL peut récupérer une page de réservations et leur historique en une seule requête au lieu d’un appel supplémentaire par réservation.

curl "https://api.useservice.app/v1/reservations?expand=events&limit=25" \
  -H "Authorization: Bearer $SERVICE_API_KEY"

{
  "object": "reservation",
  "id": "resv_8xKQ2m4Vd0pErJ7sN1aZ9bQ",
  "events": [
    {
      "object": "reservation_event",
      "id": "evt_5pQ…",
      "type": "reservation.created",
      "created_at": "2026-06-28T19:30:00+02:00"
    },
    {
      "object": "reservation_event",
      "id": "evt_7rT…",
      "type": "reservation.confirmed",
      "created_at": "2026-06-28T19:31:12+02:00"
    }
  ],
  "party_size": 4
}

Règles et limites

• La profondeur d’extension est plafonnée à 2 niveaux. Le graphe est volontairement peu profond, donc cela suffit pour atteindre le client d’une réservation.
• Sur les points de terminaison de liste, l’extension est autorisée mais la taille de page est réduite. Lorsqu’un expand est présent sur une requête de liste, le limit maximum est abaissé (à 25) pour borner le coût du chargement anticipé. Voir Pagination.
• Objets toujours intégrés. Certaines données liées sont suffisamment petites pour être toujours incluses en ligne et ne nécessitent aucun expand — par exemple les tables d’une réservation (chacune avec sa section).

Mise en cache avec les ETags

Les GET de ressource unique renvoient un ETag. Renvoyez-le comme If-None-Match à la requête suivante ; si rien n’a changé, vous obtenez un 304 Not Modified sans corps, ce qui économise de la bande passante et un peu de budget de limite de débit.

# First request — note the ETag in the response
curl -i "https://api.useservice.app/v1/reservations/resv_8xKQ2m4Vd0pErJ7sN1aZ9bQ" \
  -H "Authorization: Bearer $SERVICE_API_KEY"
# → ETag: W/"resv_8xKQ2m4Vd0pErJ7sN1aZ9bQ-1719515575000000"

# Later — pass it back; unchanged resources return 304
curl -i "https://api.useservice.app/v1/reservations/resv_8xKQ2m4Vd0pErJ7sN1aZ9bQ" \
  -H "Authorization: Bearer $SERVICE_API_KEY" \
  -H 'If-None-Match: W/"resv_8xKQ2m4Vd0pErJ7sN1aZ9bQ-1719515575000000"'
# → HTTP/1.1 304 Not Modified