During story #24970 and earlier stories, we added dedicated "business" objects to represent artifact links. It is good, as previously everything was represented by an array with variable keys and inconsistent values. Although we still need to convert back to this array for validating / saving the links, we now have objects with well-defined shapes, which is better.
However, we started defining these objects based on the REST API use-case, where we can receive "submitted links" and must compute a diff with "existing links" from the database. There are other situations where we just want to add one or several links, or change link types, but without removing any of the other existing links. There are also situations where we just want to remove one or several links, but without touching the other existing links. Doing a diff with existing links in these situations becomes very complicated, so we added inconsistent properties to our objects to handle those cases.
It becomes even more complicated in the case of "reverse" links, currently only provided by the REST API. For those links also, we receive "submitted links" and must compute a diff with "existing links" from the database. Then, for each reverse link, we "flip it" and update the source artifact and add/change/remove one link to the target artifact. You can see how it becomes very complicated to perform a diff for reverse links, and then set the correct "added" or "removed" properties for each link.
Instead of this, we should define "Order" objects that represent our intention. An "order" object represent a request to make a change to artifact links. They hold a list of links we want to add, a list of links where we want to change their types, and a list of links we want to remove. Each of these lists can be empty (which means "do nothing"). These "order" objects can handle all situations: we can compute a diff of "submitted links" and "existing links" and build an "order" from those. We can also set directly the order to add links, or remove links.
It should make reasoning about artifact links simpler, both in the case of "forward" and "reverse" links.