É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. La relation extensible est guest :

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
}

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