Include parameters, and the query language they become

An include parameter added for one consumer, and eleven values later it is a query language with no grammar.

GET /api/orders?include=lines,customer,customer.addresses,
  shipments.tracking,invoice,invoice.lines,refunds

the questions nobody had answered:
  how deep may it nest?        undefined. 3 works.
  can it be combined with
    sparse fieldsets?          only for some resources
  what is the cost of the
    worst request?             41 queries, measured
    after somebody sent it

the fix: an allow-list per endpoint, a documented depth
limit of two, and a cost budget checked before the
query runs.

An include parameter is a small query language and the moment it exists somebody will send the maximum. Publishing the allow-list turns it back into an API — a consumer can see what is available rather than guessing — and the cost check is what stops one request from being an outage.