Use the /references/outgoing endpoint to retrieve outgoing references for items. This endpoint allows batch lookups by allowing multiple items to be looked at the same time
Examples:
A simple lookup of the outgoing references for one item
The default depth to look for references in an item is 1. If it is depth.reached and there are more references that are found in the item, the result code that is returned indicates that there are more references.
You can then either query at a higher depth or query for all items which have non empty excluded arrays.
The results are returned in a key value format with the references field where the key is the content hub ID of the item.
In Graph terminology, each element in the references object is a Node and the array of IDs in the included array on each Node is an outgoing edge to another node.
Request:
{
"root" : "content:0e28db52-a916-49ea-9bde-9f014bc6f691"
}
Response:
{
"root": "content:0e28db52-a916-49ea-9bde-9f014bc6f691",
"result": {
"status": "ok",
"depth": 1
},
"next": {
"roots": [
[
"content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0"
]
],
"filters": {
"filterType": "include",
"classifications": [],
"statuses": []
},
"depth": 1,
"metadata": true,
"fl": []
},
"references": {
"content:81baa86e-ee94-45de-8e90-b23d8ef84e45": {
"id": "81baa86e-ee94-45de-8e90-b23d8ef84e45",
"classification": "content",
"included": [],
"excluded": [
"content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0"
]
},
"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca": {
"id": "bd078b79-7e1a-49e0-b3dd-e2540ac93eca",
"classification": "content-type",
"included": [],
"excluded": []
},
"content:0e28db52-a916-49ea-9bde-9f014bc6f691": {
"id": "0e28db52-a916-49ea-9bde-9f014bc6f691",
"classification": "content",
"included": [
"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca",
"content:81baa86e-ee94-45de-8e90-b23d8ef84e45"
],
"excluded": []
}
}
}
A simple lookup of the outgoing references for one item with metadata
Instead of just getting a graph of content hub IDs, you can also request to retrieve metadata for each item.
The metadata returned are the default fields that are returned by the authoring search API (authoring/v1/search).
Request:
{
"root" : "content:0e28db52-a916-49ea-9bde-9f014bc6f691",
"metadata" : true
}
Response:
{
"root": "content:0e28db52-a916-49ea-9bde-9f014bc6f691",
"result": {
"status": "ok",
"depth": 1
},
"references": {
"content:81baa86e-ee94-45de-8e90-b23d8ef84e45": {
"id": "81baa86e-ee94-45de-8e90-b23d8ef84e45",
"classification": "content",
"metadata": {
"id": "content:81baa86e-ee94-45de-8e90-b23d8ef84e45",
"name": "Slide7",
"classification": "content",
"type": "Slide",
"typeId": "cad2e430-beed-40d0-bb57-1c86c4f912c0",
"locale": "en",
"lastModified": "2017-06-09T01:21:31.369Z",
"lastModifier": "Thomas Watson",
"lastModifierId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa",
"created": "2017-06-09T01:21:17.630Z",
"creator": "Thomas Watson",
"creatorId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa",
"status": "ready"
},
"included": [],
"excluded": [
"content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0"
]
},
"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca": {
"id": "bd078b79-7e1a-49e0-b3dd-e2540ac93eca",
"classification": "content-type",
"metadata": {
"id": "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca",
"name": "Slideshow",
"classification": "content-type",
"lastModified": "2017-06-09T01:18:08.301Z",
"lastModifier": "Thomas Watson",
"lastModifierId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa",
"created": "2017-06-09T01:15:56.578Z",
"creator": "Thomas Watson",
"creatorId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa",
"status": "ready"
},
"included": [],
"excluded": []
},
"content:0e28db52-a916-49ea-9bde-9f014bc6f691": {
"id": "0e28db52-a916-49ea-9bde-9f014bc6f691",
"classification": "content",
"metadata": {
"id": "content:0e28db52-a916-49ea-9bde-9f014bc6f691",
"name": "MySlideshow",
"classification": "content",
"type": "Slideshow",
"typeId": "bd078b79-7e1a-49e0-b3dd-e2540ac93eca",
"locale": "en",
"lastModified": "2017-06-09T01:22:34.049Z",
"lastModifier": "Thomas Watson",
"lastModifierId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa",
"created": "2017-06-09T01:18:58.426Z",
"creator": "Thomas Watson",
"creatorId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa",
"status": "ready"
},
"included": [
"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca",
"content:81baa86e-ee94-45de-8e90-b23d8ef84e45"
],
"excluded": []
}
}
}
Using fl parameter to request specific metadata fields
Just like the search API, the fl parameter can be used to request specific fields, which include the document field, which is the entire API representation of the item.
Note: When the fl parameter is used, the id field is also always returned.
Request:
{
"root" : "content:0e28db52-a916-49ea-9bde-9f014bc6f691",
"metadata" : true,
"fl" : ["name"]
}
Response:
{
"root": "content:0e28db52-a916-49ea-9bde-9f014bc6f691",
"result": {
"status": "ok",
"depth": 1
},
"references": {
"content:81baa86e-ee94-45de-8e90-b23d8ef84e45": {
"id": "81baa86e-ee94-45de-8e90-b23d8ef84e45",
"classification": "content",
"metadata": {
"id": "content:81baa86e-ee94-45de-8e90-b23d8ef84e45",
"name": "Slide7"
},
"included": [],
"excluded": [
"content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0"
]
},
"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca": {
"id": "bd078b79-7e1a-49e0-b3dd-e2540ac93eca",
"classification": "content-type",
"metadata": {
"id": "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca",
"name": "Slideshow"
},
"included": [],
"excluded": []
},
"content:0e28db52-a916-49ea-9bde-9f014bc6f691": {
"id": "0e28db52-a916-49ea-9bde-9f014bc6f691",
"classification": "content",
"metadata": {
"id": "content:0e28db52-a916-49ea-9bde-9f014bc6f691",
"name": "MySlideshow"
},
"included": [
"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca",
"content:81baa86e-ee94-45de-8e90-b23d8ef84e45"
],
"excluded": []
}
}
}
Multiple items can be looked up at once by specifying multiple roots
Note: Items are not duplicated twice in the references map. It is just a key value of content hub ID to data.
Request:
{
"roots" : [ "content:7015a689-91df-407e-9c1b-39ead6c37e89",
"content:af988817-fcae-4070-a987-93cb99e4f81d"]
}
Response:
{
"roots": [
"content:7015a689-91df-407e-9c1b-39ead6c37e89",
"content:af988817-fcae-4070-a987-93cb99e4f81d"
],
"result": {
"status": "ok",
"depth": 1
},
"references": {
"content:7015a689-91df-407e-9c1b-39ead6c37e89": {
"id": "7015a689-91df-407e-9c1b-39ead6c37e89",
"classification": "content",
"included": [
"content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0"
],
"excluded": []
},
"content:af988817-fcae-4070-a987-93cb99e4f81d": {
"id": "af988817-fcae-4070-a987-93cb99e4f81d",
"classification": "content",
"included": [
"content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0"
],
"excluded": []
},
"content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0": {
"id": "cad2e430-beed-40d0-bb57-1c86c4f912c0",
"classification": "content-type",
"included": [],
"excluded": []
}
}
}
Using Filters
You can use some basic filters based on the item type such as content or asset and based on the status of the item such as ready or draft.
For example, when you use the filter "content" it returns only items of type content.
Request:
{
"root":"content:0e28db52-a916-49ea-9bde-9f014bc6f691",
"filters":{
"classifications":[
"content"
]
}
}
Response:
{
"root": "content:0e28db52-a916-49ea-9bde-9f014bc6f691",
"result": {
"status": "ok",
"depth": 1
},
"references": {
"content:81baa86e-ee94-45de-8e90-b23d8ef84e45": {
"id": "81baa86e-ee94-45de-8e90-b23d8ef84e45",
"classification": "content",
"included": [],
"excluded": []
},
"content:0e28db52-a916-49ea-9bde-9f014bc6f691": {
"id": "0e28db52-a916-49ea-9bde-9f014bc6f691",
"classification": "content",
"included": [
"content:81baa86e-ee94-45de-8e90-b23d8ef84e45"
],
"excluded": []
}
}
}
User roles: admin, manager, editor, viewer