Best Practice | Using ?expand Parameter

Feature Description

The expand query parameter instructs the ADF BC REST framework to inline child resource data directly within the parent response payload. By default, a GET request returns child resources as navigational links only. Using ?expand replaces those links with the full child data, reducing the number of round trips required to retrieve related records.

Integrators currently parsing expanded child resources as arrays who upgrade to Framework v3 or later will need to update their parsing logic to handle the collection object structure.

Why Use Expand

By default, retrieving a parent record and its child records requires separate API calls, one for the parent collection, then one per parent record to fetch its children. On a dataset with 50 subcontracts, that is 51 calls. With expand, this becomes a single request. This is particularly valuable for:

Initial data loads - Syncing AP voucher data into an external system can retrieve each voucher header together with its GL distribution lines in one pass, rather than making a separate call per voucher. Without expand, a batch of 100 vouchers requires 101 calls.

// voucher header + GL distribution lines 
{{CMIC_BaseUrl}}/ap-rest-api/rest/1/apallvouchers?expand=ApAllVoucherDetailViewObj

Reducing throttling risk - CMiC enforces a limit of 5 concurrent calls per IP. A nightly sync that retrieves manual checks and then loops through each one to fetch payment lines will quickly exhaust this limit on large datasets. Using expand collapses the entire dataset into a single request regardless of record volume.

// manual check header + payment lines 
{{CMIC_BaseUrl}}/ap-rest-api/rest/1/manualcheck/{id}/child/VouChqViewObj/{id}

Project and change order integrations - Syncing PCIs into a project management or cost control tool needs both the change order header and its cost/billing detail lines to map their data model. Both can be retrieved together in one request.

// change order header + detail lines 
{{CMIC_BaseUrl}}/cm-rest-api/rest/1/cmmast?expand=RtiGenericCmDetailViewObj

Subcontract integrations - Syncing subcontract data into a compliance, document management, or owner-facing tool needs both the subcontract header and its schedule of values lines. Using expand avoids building multi-call logic in application code.

// subcontract header + schedule of values lines 
{{CMIC_BaseUrl}}/pm-rest-api/rest/1/scmast?expand=RtiGenericScSchedViewObj

Syntax:

Use Case	Example
Expand a single child	?expand=ChildResourceName
Expand all available children	?expand=all
Combined with other parameters	?expand=ChildResourceName&q=...&fields=...&limit=...

NOTE (Performance Warning): Using expand=all on a large parent collection will fetch all child resources for every parent record returned, which can result in significant response sizes and slower performance. Best practice is to expand only the specific child resource(s) required for your use case, and combine with the fields parameter to limit the attributes returned on both the parent and child records.

Finding the Child Resource Name

The exact child resource name required by expand is not always obvious from the endpoint path. Use the /describe endpoint to discover all available child resources for a given endpoint before constructing your request.

{{CMIC_BaseUrl}}/jc-rest-api/rest/1/jcjob/describe

The response will include a children section listing each available child resource name. For more information on using /describe, see Best Practice | Endpoint Introspection.

Framework Version Impact

The structure of expanded child data in the response differs depending on the REST Framework Version declared in the request header. This is a breaking change that affects how the child payload must be parsed.

Framework v1/v2: Child resources are returned as a flat array [ ]
Framework v3 and later: Child resources are returned as a collection object { } containing count, hasMore, limit, offset, and items

Framework v3 example of an expanded child response:

json 
"ApAllVoucherDetailViewObj": { 
  "count": 5, 
  "hasMore": false, 
  "limit": 25, 
  "offset": 0, 
  "items": [ 
    { ... }, 
    { ... } 
  ] 
}

NOTE (Parsing Compatibility Warning): If your integration currently parses expanded child resources as a flat array, upgrading to Framework v3 or later will break that parsing logic. You must update your code to handle the collection object structure (including hasMore for pagination) before changing your Rest-Framework-Version header.

Framework Version Support