# Hydration

Hydration lets you embed related data in a single API response, reducing the number of round-trips needed to
assemble a complete view of a resource.

## How it works

Apiera provides two query parameters for hydration:

- **`include[resourceName]=true`** - Adds an array of related resource **UUIDs** to the response.
- **`expand[resourceName]=true`** - Adds an array of full **resource objects** to the response.


You can use them independently or together. If you only need to know which resources are linked, use `include[]`.
If you need the full data, use `expand[]`.

## Example

**Without hydration** - returns only the product's own fields:


```bash
curl https://api.apiera.io/v1/products/{uuid} \
  -H "Authorization: Bearer {token}"
```

**With include** - adds arrays of related UUIDs:


```bash
curl "https://api.apiera.io/v1/products/{uuid}?include[productAttributes]=true&include[productCategories]=true" \
  -H "Authorization: Bearer {token}"
```


```json
{
  "uuid": "a1b2c3d4-...",
  "type": "simple",
  "status": "published",
  "productAttributeUuids": [
    "6ba7b810-...",
    "7c9e6679-..."
  ],
  "productCategoryUuids": [
    "f47ac10b-..."
  ]
}
```

**With expand** - adds full resource objects:


```bash
curl "https://api.apiera.io/v1/products/{uuid}?include[productAttributes]=true&expand[productAttributes]=true" \
  -H "Authorization: Bearer {token}"
```


```json
{
  "uuid": "a1b2c3d4-...",
  "type": "simple",
  "status": "published",
  "productAttributes": [
    {
      "uuid": "6ba7b810-...",
      "productUuid": "a1b2c3d4-...",
      "attributeUuid": "d1234567-...",
      "isVariant": false,
      "createdAt": "2026-03-10T12:00:00Z",
      "updatedAt": "2026-03-10T12:00:00Z"
    }
  ]
}
```

## Available hydration options

### Product

| Parameter | Description |
|  --- | --- |
| `productAssets` | Linked assets with type and sort order. |
| `productAttributes` | Linked attributes. |
| `productAttributeTerms` | Linked attribute terms. |
| `productCategories` | Linked categories. |
| `productTags` | Linked tags. |
| `productInputValues` | Input values (field content), scoped by channel and locale. |
| `relations` | Linked product relations. |
| `completeness` | Product completeness data (expand only). |


### Asset

| Parameter | Description |
|  --- | --- |
| `metadata` | Key-value metadata pairs. |
| `files` | File versions with MIME type, size, and checksum. |


### Taxonomy resources (Attribute, Category, Tag, Brand)

| Parameter | Description |
|  --- | --- |
| `contents` | Localized content for the resource. |


## Hydration on list endpoints

Hydration works on both single-resource (`GET /v1/products/{uuid}`) and list (`GET /v1/products`) endpoints. On list
endpoints, the system fetches related data for all resources on the page in a single batch query, avoiding N+1
performance issues.


```bash
curl "https://api.apiera.io/v1/products?expand[productCategories]=true&expand[productTags]=true" \
  -H "Authorization: Bearer {token}"
```

## Visibility rules

Hydrated collections respect the same visibility rules as standard queries:

- **Soft-deleted** resources are excluded from hydrated collections.
- **Product relations** only include products that are published.


This means you always get a consistent view of active, visible data without needing to filter client-side.

## Performance considerations

- Only request the hydration you need. Each `include[]` or `expand[]` adds a query on the server side.
- `include[]` (UUIDs only) is cheaper than `expand[]` (full objects) when you only need to know what's linked.
- For list endpoints, hydration is batched per page. Smaller page sizes mean less data per hydration query.