---
schema_version: "1"
id: 72c9fda7b9c5b839b0a20cb5b63ec7e8e614f696e0ba3eac99b8a47aa8159dbe
title: OData $expand in APIkit for OData v4
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/apikit/latest/apikit-odatav4-expand-feature.md
canonical_url: https://docs.mulesoft.com/apikit/latest/apikit-odatav4-expand-feature
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 152c5a7722ad71b6f8e1522eb1a64637f162c561266260dc39ceb3d73ba1a19e
description: MuleSoft Documentation Site
release: 4.x
latest: true
---
---
product: APIkit
version: 4.x
is-latest-version: true
---

# OData $expand in APIkit for OData v4

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The OData `$expand` system query option returns related entities inline so clients avoid extra round
trips and smaller payloads on metered or high-latency networks. APIkit for OData v4 adds automatic
routing for common `$expand` scenarios from module 1.3.0 onward; you configure listeners and
optional generic expansion so existing flows can satisfy expanded queries. See the
[OASIS URL conventions](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html)
for full `$expand` syntax.

## Before You Begin

Prerequisites for using `$expand` include:

- APIkit for OData Module (version 1.3.0)

- A `<request-entity-collection-listener/>` implementation for each expandable entity

- Support for the `in` filter on the `<request-entity-collection-listener/>` flows

## `$expand` Feature Example

In this example:

- The `Employee` entity has a related `Manager` entity.

- The `Employees` entity set is a collection of `Employee` entities.

- The `Managers` entity set is a collection of `Manager` entities.

- The API location is `https://example.com/api/`.

Given this setup, the following requests retrieve employees and their managers:

- Use `GET https://example.com/api/Employees` to retrieve a list of employees.

- Gather the `Manager` IDs through the `ReferentialConstraint` of their relationship.

- Use `GET https://example.com/api/Managers?$filter=ManagerID in (id1, id2, ..., idN)` to retrieve a
  list of related managers.

- Write a small program to merge the lists based on join criteria.

If you use the `$expand` feature, the request to retrieve a list of employees with their `Manager`
navigation property expanded is `GET https://example.com/api/Employees?$expand=Manager`.

## The `generic expand` Feature

Reuse existing flow implementations as a starting point for expanding requests by using the
`generic expand` feature, which enables you to focus on the relevant data retrieval operations while
the module performs the necessary steps to ensure that the `$expand` fields are complete.

An application with the `generic expand` feature enabled works like any other OData Mule
application. However, during the flow execution, once the module retrieves information for the main
entity set, it performs additional internal requests to gather the information for any `expand`
field.

You can configure how the software handles errors during the expansion operation:

- Fails the request with an error.

- Replaces the failed expansion with a `null` value.

## The `generic expand` Operation

The `generic expand` feature dispatches additional queries to the application when the original flow
completes. Because this is done based on the application `EDM`, you must make extra annotations to
add enough context to the module:

- The `EntitySet` where the expansion takes place has a `NavigationPropertyBinding` for every
  expandable `NavigationProperty` of its `Entity`.

  This is used to select which `<entity-collection-source/>` is executed when expanding that
  property.

- Each expandable `NavigationProperty` has a `ReferentialConstraint` attached.

  Internal requests use `ReferentialConstraint` when matching the value of `Property` against the
  value of `ReferencedProperty`.

### Flow Execution

1.  The main flow is executed and completed resulting in a collection of `entities`.

2.  The OData module gathers all the properties that need expansion.

3.  For each `NavigationProperty`:

    1.  Get the `source property` from its `ReferentialConstraint`.

    2.  Get the `referenced property` from its `ReferentialConstraint`.

    3.  Get the `destination entity set` from its `NavigationPropertyBinding`.

    4.  For each of the `entities` get the resolved `source property`. Add these values to a
        `source property list`.

    5.  Execute the internal request by invoking the `<entity-collection-source/>` for
        `destination entity set` with `$filter=referenced property` in `(…​source property list)`.

### Error Handling and Error Propagation

Error handling for OData v4 applications is local to each flow, whether you use `generic expansion`
or not. Error handling code for a given `EntitySet` belongs to the flow implementations for that
entity set, both for normal requests and for the internal requests observed during expansion
processing.

Handling errors during the expansion process is not supported, because the expansion process runs
after the execution of the flow finishes. There are two options available for handling errors:

- **Ignore errors during expansion:** Errors during generic expansion are ignored.  
  By default, the expansion of collections and single objects are resolved to empty lists and `null`
  values respectively.

- **Propagate errors during expansion:** Errors arise during generic expansion.  
  When an error reaches the OData v4 router, the original request is answered with an error
  response.

You can configure error handling **per-source** on the **Capabilities** tab.

### Limitations

- Only the first `ReferentialConstraint` is considered.

  Navigation properties that use compound keys are not supported.

- Expansion is done `field-by-field` instead of `EntitySet-by-EntitySet`.

  This can cause more internal requests than necessary.

- The expanded entities always have an `<entity-collection-source/>` implementation.

  Expansion using `<entity-source/>` implementations are not executed due to performance concerns.

## Implementation Guidelines

To implement the `generic expansion` feature, you must annotate each source with the types that it
can expand. Enabling `$expand` without restrictions enables API clients to write complex queries,
which can create performance issues.

If you implement `$expand` manually for some relationships, leave these relationships out of the
list on the **Expandable Navigation Properties** option. The navigation properties that don’t use
the `generic expansion` feature need manual implementations in the flow.

### Implementation Checklist

1.  Verify that your CSDL file and Mule application meet the expected requirements:

    - Every `NavigationProperty` has one `ReferentialConstraint`.

    - Every `EntitySet` has one `NavigationPropertyBinding` for each `NavigationProperty` of its
      entity type.

    - Every `<entity-collection-source/>` supports the `in` operator for the `$filter` system query
      option.

2.  For each source for which you enable `generic expand` support:

    1.  Open the **Capabilities** tab.

    2.  Edit inline the **Expandable navigation properties** field.

    3.  Add the name of each navigation property to be expandable by using `generic expand`.

    4.  Depending on your use case, select **Ignore errors on expand** to avoid errors during the
        generic expansion and to generate errors on the main flow.

3.  Verify that your existing flows support the `$expand` feature.

## See Also

- [APIkit for OData v4 Module Reference](https://docs.mulesoft.com/apikit/latest/apikit-odatav4-extension-reference)

- [APIkit for OData v4 Error Handling Reference](https://docs.mulesoft.com/apikit/latest/apikit-odatav4-error-handling-reference)