Calling API's in a multi-colony sharded environment.

Answer

For an API, the colony(s) to fetch data is identified by using the order precedence of FactNames given in colonyLookup.xml and Fact attributes passed in the Api input.

In the out of the box sharding logic introduced in version 9.2.1, the SellerOrganizationCode is the driver to identify colony (db shard). A new FACT type, "Store" has been added to identify the colony directly if a matching Fact attribute is present in the API input. For example, for getOrderList it is SellerOrganizationCode. The attributes ColonyId, PrimaryKey and SellerOrganizationCode comes first in the colonyLookup.xml and if none of them are present in the API input, then the input XML will be send to search against Elasticsearch index to identify the colony (provided IndexLookup is present in the colonyLookup.xml). If Elasticsearch returns more than one colony then the API framework processes the original input in each of colonies in parallel, merge the results from individual colonies and finally shows to the user who called the API..

This is done at the API framework level and this feature is available for the following APIs only. All are List Apis.

getShipmentListForOrder
getOrderReleaseList
getOrderList
getOrderLineStatusList
getOrderLineList
getOrderInvoiceList
getOrderInvoiceDetailList
getShipmentList
getShipmentLineList
getShipmentContainerList
getExceptionListForOrder
getExceptionList
getStoreBatchList
getOrdersForReturn

As per the API framework all the other get/manage/delete APIs are supposed to take the PrimaryKey in the input in a multi-colony sharded environment. i.e APIs like getOrderDetails must be called with OrderHeaderKey in the input. This is the only accurate way to getting order details from UI.

So it is recommended to call getOrderDetails only if OrderHeaderKey is known; otherwise you should call getOrderList. Both these approaches will identify colonies at the API framework level itself. i.e much before entering business logic of that API.