Document API spec. for locking & consistency of write operations