APIHub Locking Endpoints (RFC-104)

A period when the community can review the RFC (comment Docs).

Document Maintainers: Andi Gabriel Tan 2024. List of other contributors in Annex. 1.

Copyright: MIT license

Copyright © 2018-2024 Axiologic Research and Contributors.

This document is licensed under MIT license.


OpenDSU wallets in enterprise use cases require a synchronization mechanism in order to avoid unnecessary anchoring conflicts that could impact the user experience. This RFC describes some simple APIs that can solve this issue.

APIHub Locking Component

Status Code Description
/lock Query Params:
secret: is an arbitrary string that ideally is a cryptographic random number (minim 32 bytes)
id: is any string
period: is the number of milliseconds while the lock is reserved for the caller

HTTP Return Code:
200 if the lock got acquired
409 if the lock can’t be acquired (409 == conflict)
500 if the lock cannot be acquired because of a server error

The following request will put a lock on object “123” for 3 seconds.
/unlock Query Params:
secret: is an arbitrary string
id: is any string

HTTP Return Code: 200 in if the operation succeeded;
404 if failed to release the lock because doesn’t exist;
500 if the lock cannot be released because of a server error;

The following request will release the lock on object “123”

Lock Implementation

A lock is a file containing the “lock” file in a folder in /apihub-root/external-volume/locks/{folderName}, where folderName is the base58 of the id of the lock. The “lock” file contains a JSON with fields: expire and secret. The value of the “expire” field is computed as the timestamp of a moment in the future controlled by the period parameter. Supposing that the current time is greater than the “expire” value, the lock operation should succeed (unlock is not mandatory because any lock will be automatically unlocked in time). However, it is still recommended to do an unlock to ensure that other wallets will not be locked out for too long.


  1. Axiologic Research: New content and improvements. Original texts under PharmaLedger Association and Novartis funding. MIT licensed content accordingly with the contracts. Publish and maintain the www.opendsu.org site.

  2. PrivateSky Research Project: MIT licensed content accordingly with the contracts. https://profs.info.uaic.ro/~ads/PrivateSky/

Annex 1. Contributors

Current Editors Email
Sînică Alboaie sinica.alboaie@axiologic.net
Nicoleta Mihalache nicoleta@axiologic.net
Andi-Gabriel Țan andi@axiologic.net
Contributors Axiologic Research Email
Adrian Ganga adrian@axiologic.net
Andi-Gabriel Țan andi@axiologic.net
Cosmin Ursache cosmin@axiologic.net
Daniel Sava daniel@axiologic.net
Nicoleta Mihalache nicoleta@axiologic.net