Expanding objects

Related objects are ids by default

To keep responses small, related objects are returned as bare id strings rather than full objects. For example, a reservation’s guest is just the guest’s id:

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

Expanding

Use the expand parameter to inline a related object in the same response. The expandable relationship is guest:

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

Now guest is the full guest object:

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

Rules and limits

• Expansion depth is capped at 2 levels. The graph is intentionally shallow, so this is enough to reach a reservation’s guest.
• On list endpoints, expansion is allowed but page size is reduced. When any expand is present on a list request, the maximum limit is lowered (to 25) to bound the cost of eager-loading. See Pagination.
• Always-embedded objects. Some related data is small enough that it is always included inline and needs no expand — for example a reservation’s tables (each with its section).

Caching with ETags

Single-resource GETs return an ETag. Send it back as If-None-Match on the next request; if nothing changed you get a 304 Not Modified with no body, saving bandwidth and a little rate-limit budget.

# 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