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

This document is licensed under MIT license.

APIHub Locking Endpoints (RFC-104)
Abstract
APIHub Locking Component
Lock Implementation
Annex 1. Contributors

Abstract

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 Example: The following request will put a lock on object “123” for 3 seconds. /lock?key=secret&id=123&period=3000
/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; Example: The following request will release the lock on object “123” /unlock?key=secret&id=123

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

Example:
The following request will put a lock on object “123” for 3 seconds.
/lock?key=secret&id=123&period=3000

/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;

Example:
The following request will release the lock on object “123”
/unlock?key=secret&id=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.

Contributors

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.
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