Compatibility for eventually-consistent systems

This is a complex issue with a potentially extreme amount of background information, justifying a fairly simple set of changes:

  • All record types which have an id should also include a revisionId.
  • All update and delete methods should accept the revisionId of a record, instead of its id.
    • Clients should reference revisions, rather than RESTful identities, when making alterations to existing data.
    • For UI code to be correct, it must ensure it passes the correct parameter.
    • For backend systems which represent a single source of truth and do not support versioning, revisionId can simply be provided with the same value as id to no ill effects.

I will leave the background information to a minimum for now, to see how this lands with other folks (particularly @lynnfoster @mayel @ivan) before sinking time into explaining deeper.

I think this is the simplest API change that can accommodate the diverse spectrum of potential technologies to implement against— from the high-trust end of centralised, immediately consistent systems all the way through to low-trust, fully distributed and eventually-consistent networks in which forks are unavoidable.

Further reading:

Edited by pospi