api: request ID is not well defined

[exavolt]

The current implementation, we are declaring that X-Request-ID can be purposed as an idempotency token / key. The problem is that this request header is not recognized in any standard. Some are assigning request ID on the server, for example through middleware like in chi.

The idea is that this ID is serving both purposes as request / call / action identifier and as idempotency token / key. From our limited experience, both these two purposes can make use of the same identifier, but we must be sure that the identifiers are provided by the clients. We must note that these identifiers will be stored in the database.

Rather than utilizing an identifier that might cause conflict, we should utilize other identifiers that would be more accurate in declaring the intent. A good example is Stripe's Idempotency-Key[1]. Another example is AWS's ClientToken[2] but this is no as clear as Stripe's.

Some candidates: Idempotency-Key / Idempotency-Token is non-ambiguous but it might be confusing if we use it to identify a request / call / action. Action-ID / Action-Key / Action-Token is more inline with our concept of Action and Actor in iam though we must clearly declare its relation with idempotency requests / calls.

Question: do the keys need to be permanently unique or should we make them time-bound?

1: https://stripe.com/docs/api/idempotent_requests
2: https://docs.aws.amazon.com/AWSEC2/latest/APIReference/Run_Instance_Idempotency.html