Using VersionOne's RESTful API to re-rank stories

Question

How do I change the rank order of Stories through VersionOne's RESTful API?

Answer 1

If you do a data query
http://YourVersionOne/rest-1.v1/Data/Story?sel=Order,ID&sort=Order,
you will get the natural creation order of your stories in Descending order.

There are two operations: 1) insert before some story and 2)insert after some story.

GIVEN

I) Assume that I am examining a list of Stories sorted in Descending order. In this context, the use of the word "before" implies a smaller Order number.

II) Assume a fragmented list of of stories in the form of [...-(x+c),-x, x+c...] where there is no guarantee of consecutive order numbers in this list.

III) Negative Order numbers may be present

IV) I am looking at the descending order as the basis of this explanation and "smaller Order number is better" is arbitrary. Ascending frame of reference is equally valid.

Example 1: Insert before

I want to insert my Story:9999 before my Story:1234. After doing a query, I discover that

Story:9999 has an Order of 454
Story:1234 has an Order of 2048

Here is what I need to perform this order change via REST in VersionOne

VersionOne URL: https://myVersionOne/rest-1.v1/Data/Story/1234

Method: POST

Payload: <Asset> <Attribute name="Order" act="set">454+</Attribute> </Asset>

The end result is
Story:1234 has an Order < Story:9999.

The reason why i didn't give you the exact Order number of each is because I have noticed a couple of things

a) The operation could force Story:1234 to Hijack the original Order (454) and bump the Story:9999 to the next available slot and bump its inhabitant (Ala insertion sort in a fixed array scenario)

or

b) The operation could insert assign Story1234 an unused Order number that meets the condition of unusedOrderNum < Story:9999.Order. This allows Story:9999 to keep its same order number. *NOTE: These empty slots come from deletions.

Example 2: Insert after

I want to insert my Story:9999 after my Story:1234. AFter doing a query, I discover that

Story:9999 has an Order of 454
Story:1234 has an Order of 2048

Here is what I need to perform this order change via REST in VersionOne

VersionOne URL: https://myVersionOne/rest-1.v1/Data/Story/1234

Method: POST

Payload: <Asset> <Attribute name="Order" act="set">454-</Attribute> </Asset>

The end result is
Story:9999 has an Order of 454
Story:1234 has an order of 453

In summary, OrderNum+ inserts before some story s and OrderNum- appends after some story s.