Status Identifiers¶
A Status is the main entity for the Stativate Plattform and therefore the main API operations are targeting one specific status. To make the API integration as simple as possible there are two different ways to target a specific status. You can either use the status id or a status key.
A list of all the identifiers for a status can be read using the list status endpoint. This will return all status you are an owner of. The response format will look like:
[
{
"statusId": "A0aEMOe6n7qMhcExample",
"statusKey": "statuskey-1-example",
"shareId": "xkwd5e",
"name": "Status One"
}
]
Status ID¶
Every status automatically gets a unique id
when created. This id
is meant to be used with endpoints that require a :statusId
.
Status ID tutorial
For details on how to use a statusId
, see the update status value tutorial.
Using the statusId
is usually a good choice to update a static status. Imagine you want to automatically update a status showing one kpi of your business. The status creation will only happen once and therefore might as well be done manually. The updates can then be done by API using the statusId
.
Advantages using statusId
¶
For use-cases with a small number of status that need no dynamic creation, server-generated ids offer a simple way to manually maintain the status and send just value updates via API.
A statusId
is unique throughout the entire Stativate platform, so there will never be two status with the same statusId
. That means a status also has the same statusId
for all users allowed to access it. For use-cases where multiple users access the same status via API, the statusId
is the identifier to use.
Possible downsides using statusId
¶
In some cases a server-generated statusId
makes things harder than neccessary to integrate.
In use-cases with dynamically created status, the handling of statusId
might require id mapping. Data source entities usually have their own identifiers. When a status for each record from a data source is created that would mean every mapping between statusId
and the source records id would have to be saved to know what status to update in the next run.
Status Key¶
For use-cases with dynamic status creation, the Stativate API can be used with IDs defined on client-side. Those client-generated IDs are called status keys in the API. A status key is simply an id for a status that you can define yourself.
Status key tutorial
For details on how to use a statusKey
, see the create or update status tutorial.
Advantages using statusKey
¶
There is no need to maintain a mapping between data source ids and the Stativate status IDs. Status can simply be used with identifiers coming from the data source.
Possible downsides using statusKey
¶
Stativate does not ensure uniqueness for status keys across user accounts, so multiple users can not use the same status based on a status key.
You will have to ensure uniqueness yourself, otherwise you will overwrite your existing status when unintentionally using the same status key.