Rank

Arrays - Multiple documents with the same Key

The Rank allows you to have multiple documents under the same Key and Context

Pic 1: Ranked documents

It is recommended to always provide Rank=0for all operations, unless you know what you are doing and you definitely want to use ranking.

POST

POST - Update or insert with Rank

POST without an explicit Rank

If you POST a document without providing an explicit Rank this is always an insert, and a new document is created with the next available rank (highest rank +1). With reference to Pic 1 the next Rank would be 5 +1 = 6.

POST {{host}}/{{accountId}}/docs/content?key=MSPro.Test.Invoice
Content-Type: application/json
Authorization: Basic {{basic}}

{
  "InvoiceId" : "Inv002.6",  
  "Firstname": "Markus",  
  "Lastname" : "Schmidt2" 
}

POST with an explicit Rank

If you provide a specific Rank, an existing document is updated. A new document is created, if there is a no document with that Rank (insert).

POST .../docs/content?key=MSPro.Test.Invoice&Rank=6

GET

GET - Specific or latest

GET without an explicit Rank

GET {{host}}/{{accountId}}/docs/content?key=MSPro.Test.Invoice
Content-Type: application/json
Authorization: Basic {{basic}}

If you don't provide an explicit Rank the document with the highest Rank is returned - which is considered to be the latest/current document.

GET with an explicit Rank

If you provide a explicit Rank, of course, that document is returned. In case there is no document with the specified Rank you will get HTTP/1.1 404 Not Found.

DELETE

For deletion the same is true as for GET: if you don't provide an explicit Rank, the document with the highest Rank is affected. If you provide a Rank, that document is deleted or you receive a http-404 in case there is no document with that rank.

Minimum Rank

You can optionally provide a MinRank to control the next rank that is created. Normally, the next rank is highest available rank +1. If you provide a MinRank the next rank is minimum that number.

Example: Imagine the highest rank for document of Key="MSPro.Test.Invoice" is 5. You POST a new document with that Key - omitting an explicit rank - but providing a MinRank of 10. Then a next document created will have Rank=10 (not 6!).

POST {{host}}/{{accountId}}/docs/content?key=MSPro.Test.Invoice&MinRank=20
Content-Type: application/json
Authorization: Basic {{basic}}

{
  "InvoiceId" : "Inv002.20",  
  "Firstname": "Markus",  
  "Lastname" : "Schmidt2" 
}