Expanding Relationshipslink

Include related resources in a single API request using the expanded parameter. This reduces the number of API calls needed to fetch complete data.

How Expansion Workslink

With expansion, related resource identifiers are added in the relationships object, at the same level as attributes:

{
  "data": {
    "type": "failure",
    "id": "12345",
    "attributes": { ... },
    "relationships": {
      "location": {
        "data": {
          "type": "location",
          "id": "678"
        }
      },
      "problem": {
        "data": {
          "type": "problem_type",
          "id": "789"
        }
      }
    }
  }
}

And full details of the related resources are included in the included attribute, at the same level as data:

{
  "data": { ... },
  "included": [
    {
      "type": "location",
      "id": "678",
      "attributes": {
        "name": "Meeting Room",
        ... // location full details
      }
    },
    {
      "type": "problem_type",
      "id": "789",
      "attributes": {
        "name": "Air conditioner not working",
        ... // problem full details
      }
    }
  ]
}

Using the Expanded Parameterlink

Single Relationshiplink

curl "https://api.infraspeak.com/v3/failures?expanded=location" \
  -H "Authorization: Bearer YOUR_TOKEN"

Multiple Relationshipslink

Comma-separate multiple expansions:

curl "https://api.infraspeak.com/v3/failures?expanded=location,problem,client" \
  -H "Authorization: Bearer YOUR_TOKEN"

Performance Considerationslink

Expand Only What You Needlink

Each expansion adds data to the response. Only expand relationships you'll use:

# Good - expand only needed relationships
curl "https://api.infraspeak.com/v3/failures?expanded=location" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Less efficient - expanding everything/unused relationships
curl "https://api.infraspeak.com/v3/failures?expanded=location,problem,client,supplier" \
  -H "Authorization: Bearer YOUR_TOKEN"

N+1 Query Problemlink

Expansion helps avoid the N+1 query problem:

# Without expansion - N+1 queries (bad)
failures = requests.get("/failures").json()["data"]
for failure in failures:
    location_id = failure["attributes"]["local_id"]
    location = requests.get(f"/locations/{location_id}").json()["data"]
    # 1 + N API calls

# With expansion - 1 query (good)
failures = requests.get("/failures?expanded=location").json()["data"]
for failure in failures:
    location = failure["relationships"]["location"]["data"]
    # 1 API call total

Pagination with Expansionlink

Expansion works with pagination:

curl "https://api.infraspeak.com/v3/failures?expanded=location&limit=50&page=2" \
  -H "Authorization: Bearer YOUR_TOKEN"

Missing Relationshipslink

When a relationship doesn't exist, the data field is null:

{
  "data": {
    "type": "failure",
    "id": "12345",
    "attributes": { ... },
    "relationships": {
      "supplier": {
        "data": null
      }
    }
  }
}