Update work item relations/links in VS Team Services - azure-devops

Question

I am trying to use the VSTS API to remove all parent links on items, and set those parents as related items.
https://www.visualstudio.com/en-us/docs/integrate/api/wit/work-items#update-work-items
I do not fully understand how the "Path" needed to remove relations work – I am getting inconsistent results where sometimes it works, sometimes not (so, im clearly doing it wrong)
I am making an assumption that its simply the order returned by the API. So, for example:
Index[0] item
Index[1] item
Index[2] item <- this is the one I want to remove, so I use index 2
public void RemoveParentLink(int pathIndex, int itemToUpdate, string link)
{
JsonPatchDocument patchDocument = new JsonPatchDocument();
patchDocument.Add(
new JsonPatchOperation()
{
Operation = Operation.Remove,
Path = $"/relations/{pathIndex}"
}
);
WorkItem result = witClient.UpdateWorkItemAsync(patchDocument, itemToUpdate).Result;
}
The documentation states that Path is:
Path to the value you want to add, replace, remove, or test.
For a specific relation, use "relations/Id".
For all relations, use "/relations/-".
Index is NOT the Id of course, but how do I get the relation/Id exactly?

Answer 1

Using GetWorkItemAsync or GetWorkItemsAsync with WorkItemExpand.Relations parameter to get linked work items.
Var workItem=witClient.GetWorkItemAsync(id: [work item id], expand: Microsoft.TeamFoundation.WorkItemTracking.WebApi.Models.WorkItemExpand.Relations).Result.
Then the index is the index of relations.

Answer 2

The 'id' in the '/relation/id' path is a index in fact. You retrieve the work item definition, then the 'id' is the index of the link in the 'relations' array. Hence your assumption is right.
Evidence: given a work item with 2 links, if you try to delete/modify id >= 2 it will answer with:
{ "$id": "1", "innerException": null, "message": "Index out of range
for path /relations/2.", "typeName":
"Microsoft.VisualStudio.Services.WebApi.Patch.PatchOperationFailedException,
Microsoft.VisualStudio.Services.WebApi, Version=14.0.0.0,
Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "typeKey":
"PatchOperationFailedException", "errorCode": 0, "eventId": 3000 }
0 and 1 as id work just fine instead.
I may be wrong, but I could guess that you could get an error when using the 'replace' operation before the 'add' operation. For example you need to add a 'comment' inside the 'attributes' of a link before modifying (i.e. 'replace' operation) its value.