SchemaStack

Appearance

Expanding Relationships ​

When your entities have relationships (e.g., an Order belongs to a Customer), the API returns only the foreign key by default. Use the expand query parameter to include the full related object in the response.

Default Behavior (No Expand) ​

Without expand, a foreign key column is returned as a plain value:

http
GET /api/v1/acme-corp/sales/Order/1
Authorization: Bearer sk_live_abc123...
json
{
  "data": {
    "id": 1,
    "orderNumber": "ORD-001",
    "total": 150.0,
    "customerId": 42
  }
}

Expanding a Relationship ​

Add ?expand=customer to include the full customer object:

http
GET /api/v1/acme-corp/sales/Order/1?expand=customer
Authorization: Bearer sk_live_abc123...
json
{
  "data": {
    "id": 1,
    "orderNumber": "ORD-001",
    "total": 150.0,
    "customerId": 42,
    "customer": {
      "id": 42,
      "name": "Jane Doe",
      "email": "[email protected]"
    }
  }
}

Multiple Relationships ​

Expand several relationships at once by separating them with commas:

http
GET /api/v1/acme-corp/sales/Order?expand=customer,lineItems
json
{
  "data": [
    {
      "id": 1,
      "orderNumber": "ORD-001",
      "total": 150.0,
      "customer": {
        "id": 42,
        "name": "Jane Doe",
        "email": "[email protected]"
      },
      "lineItems": [
        { "id": 1, "productName": "Widget", "quantity": 2 },
        { "id": 2, "productName": "Gadget", "quantity": 1 }
      ]
    }
  ],
  "meta": { "page": 0, "size": 20, "totalElements": 1, "totalPages": 1 }
}

Nested Expansion ​

Use dot notation to expand relationships on related objects. For example, if a LineItem belongs to an Order, and the Order belongs to a Customer:

http
GET /api/v1/acme-corp/sales/LineItem?expand=order.customer
json
{
  "data": [
    {
      "id": 1,
      "productName": "Widget",
      "quantity": 2,
      "order": {
        "id": 1,
        "orderNumber": "ORD-001",
        "customer": {
          "id": 42,
          "name": "Jane Doe",
          "email": "[email protected]"
        }
      }
    }
  ],
  "meta": { "page": 0, "size": 20, "totalElements": 1, "totalPages": 1 }
}

You can combine nested and flat expansions: ?expand=order.customer,warehouse.

Works on All Read Endpoints ​

The expand parameter works on both list and single-record endpoints:

GET /api/v1/{org}/{workspace}/{entity}?expand=customer          # list
GET /api/v1/{org}/{workspace}/{entity}/{id}?expand=customer     # single record

Admin Configuration ​

Workspace administrators can configure expansion behavior per entity:

Default Expand ​

Set a default expansion that applies when no ?expand parameter is provided. For example, if defaultExpand is set to customer, then GET /orders automatically expands the customer relationship without the caller needing to specify it.

An explicit ?expand= parameter always overrides the default.

Expandable Relationships (Whitelist) ​

Restrict which relationships can be expanded. When a whitelist is configured, requesting an unlisted relationship returns 400 Bad Request:

json
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Relationship 'internalNotes' is not expandable. Allowed: customer,lineItems"
  }
}

When no whitelist is configured, all relationships are expandable.

Maximum Depth ​

The maximum nesting depth for dot-notation expansion (defaults to 3). Exceeding the limit returns 400 Bad Request:

json
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Expand depth exceeds maximum of 2: order.customer.address"
  }
}

Performance Notes ​

  • Expanded relationships are loaded using SQL JOIN FETCH, which avoids the N+1 query problem
  • Pagination remains accurate when using expand — the total count is computed separately
  • Only expand what you need. Each expanded relationship adds a JOIN to the underlying query

SchemaStack Documentation