Retrieve references endpoint replaced
Deprecation notice
Beginning with the Platform 6 release, the /references-to endpoint is deprecated in favor of the /discoverReferences endpoint.
Retrieve references prior to Platform 6
In early versions of Itential Platform (IP/2022.1 through IP/2023.2), the /references-to endpoint was used to retrieve assets that reference a target asset. The endpoint requires two query parameters: target-type and target-identifiers.
The examples below demonstrate a proper GET request to /references-to and the expected response. In this example, the target asset is a workflow named childWorkflow that is referenced by two other workflows named parentWorkflow1 and parentWorkflow2.
GET request
Response
/references-to can only look “upward.” In a child-parent relationship like this example, running /references-to on one of the parent workflows returns no assets, since nothing is referencing either of them.
Retrieve references in Platform 6 and later
With the Platform 6 release, the /discoverReferences endpoint provides a wider range of functionality for retrieving relevant assets for a particular asset, including projects. With /discoverReferences, you can specify the direction to search relative to the target asset (up, down, or all) and whether the search should be executed recursively past just one layer up or down (recursive: true or false).
This endpoint fully encompasses the designed functionality of /references-to. The previous example can be reproduced with /discoverReferences as shown below.
POST request
/automation-studio/discoverReferences
With the following body:
In this example, only workflow references are searched, but any of the asset tags listed in the metadata.ignore of the response can be added to the include property with a specified direction (up, down, or all).
Response
A data array containing the root resource and the retrieved assets:
If you set includeResources to true in the POST request body, each item in the data array will include a resource property containing the entire data object for that asset.
Enable the recursive property
If you add another workflow named grandparentWorkflow that references parentWorkflow1 and switch the recursive property to true, the response includes grandparentWorkflow even though it does not directly reference childWorkflow — it is found through the recursive upward search.
Response:
