Real Locker API documentation v1


1. HTTP API

Operation: Ping

Endpoint: /ping

Method: GET

Description: Check service availability


Operation: Lock

Endpoint: /lock

Method: POST

Description: Try to perform lock

Request body:

{
  "authToken": string,  // Company token, required
  "lockType": string,   // Type of the lock, required
  "userId": string,     // ID of the lock owner, required
  "timeout": int,       // Lock timeout in seconds, required
  "idsToLock": string[] // Array of IDs that should be locked, required
}

Request example:

{
  "authToken": "abcdef1234567890",
  "lockType": "readLock",
  "userId": "123abc",
  "timeout": 600,
  "idsToLock": [
    "1a",
    "2b"
  ]
}

Response body:

{
  "succeeded": boolean,   // Is lock was succeeded
  "errorMessage": string, // Error message if lock was unsucceeded
  "locksInfo": LockInfo[] // Information about existing locks
}

Response example:

{
  "succeeded": false,
  "errorMessage": "Some of the provided ids are already locked by another user",
  "locksInfo": [
    {
      "lockType": "readLock",
      "userId": "456eee",
      "timeLeft": 60,
      "lockedId": "1a"
    }
  ]
}

Operation: Unlock

Endpoint: /unlock

Method: POST

Description: Try to perform unlock

Request body:

{
  "authToken": string,    // Company token, required
  "lockType": string,     // Type of the lock, required
  "userId": string,       // ID of the lock owner, required
  "idsToUnlock": string[] // Array of IDs that should be unlocked, required
}

Request example:

{
  "authToken": "abcdef1234567890",
  "lockType": "readLock",
  "userId": "123abc",
  "idsToUnlock": [
    "1a",
    "2b"
  ]
}

Response body:

{
  "succeeded": boolean,  // Is unlock was succeeded
  "errorMessage": string // Error message if unlock was unsucceeded
}

Response example:

{
  "succeeded": true,
  "errorMessage": null
}

Operation: List

Endpoint: /list

Method: POST

Description: Get the list of locks

Request body:

{
  "authToken": string, // Company token, required
  "lockType": string,  // Type of the lock, required if userId is not specified
  "userId": string     // ID of the lock owner, required if lockType is not specified
}

Request example:

{
  "authToken": "abcdef1234567890",
  "lockType": "readLock",
  "userId": "123abc"
}

Response body:

{
  "succeeded": boolean,   // Is list operation was succeeded
  "errorMessage": string, // Error message if list operation was unsucceeded
  "locksInfo": LockInfo[] // Information about existing locks
}

Response example:

{
  "succeeded": true,
  "errorMessage": null,
  "locksInfo": [
    {
      "lockType": "readLock",
      "userId": "456eee",
      "timeLeft": 60,
      "lockedId": "1a"
    }
  ]
}

Operation: Clear

Endpoint: /clear

Method: POST

Description: Clear locks

Request body:

{
  "authToken": string, // Company token, required
  "lockType": string,  // Type of the lock
  "userId": string     // ID of the lock owner
}

Request example:

{
  "authToken": "abcdef1234567890",
  "lockType": "readLock",
  "userId": "123abc"
}

Response body:

{
  "succeeded": boolean,  // Is clear operation was succeeded
  "errorMessage": string // Error message if clear operation was unsucceeded
}

Response example:

{
  "succeeded": true,
  "errorMessage": null
}

2. WebSockets API

All operations are made through WebSocket endpoint /ws

Operation: Ping

Description: Check service availability

Request body:

{
  "operation": "PING",         // Always pass this value
  "operationRequestJson": "{}" // Use empty JSON
}

Response body:

{
  "succeeded": boolean,     // Is WebSocket request was succeeded
  "operation": "PING",      // Always returns this value
  "errorMessage": string,   // Error message if WebSocket request was unsucceeded
  "operationResponse": null // We don't have any response for ping
}

Response example:

{
  "succeeded": true,
  "operation": "PING",
  "errorMessage": null,
  "operationResponse": null
}

Operation: Lock

Description: Try to perform lock

Request body:

{
  "operation": "LOCK",           // Always pass this value
  "operationRequestJson": string // LockRequest JSON
}

Request example:

{
  "operation": "LOCK",
  "operationRequestJson": "{ 
      'authToken': 'abcdef1234567890',
      'lockType': 'readLock',
      'userId': '123abc',
      'idsToLock': [
        '1a',
        '2b'
      ]
    }"
}

Response body:

{
  "succeeded": boolean,             // Is WebSocket request was succeeded
  "operation": "LOCK",              // Always returns this value
  "errorMessage": string,           // Error message if WebSocket request was unsucceeded
  "operationResponse": LockResponse // Internal operation response
}

Response example:

{
  "succeeded": true,
  "operation": "LOCK",
  "errorMessage": null,
  "operationResponse": {
    "succeeded": false,
    "errorMessage": "Some of the provided ids are already locked by another user",
    "locksInfo": [
      {
        "lockType": "readLock",
        "userId": "456eee",
        "timeLeft": 60,
        "lockedId": "1a"
      }
    ]
  }
}

Operation: Unlock

Description: Try to perform unlock

Request body:

{
  "operation": "UNLOCK",         // Always pass this value
  "operationRequestJson": string // UnlockRequest JSON
}

Request example:

{
  "operation": "UNLOCK",
  "operationRequestJson": "{ 
      'authToken': 'abcdef1234567890',
      'lockType': 'readLock',
      'userId': '123abc'
      'idsToUnlock': [
        '1a',
        '2b'
      ]
    }"
}

Response body:

{
  "succeeded": boolean,               // Is WebSocket request was succeeded
  "operation": "UNLOCK",              // Always returns this value
  "errorMessage": string,             // Error message if WebSocket request was unsucceeded
  "operationResponse": UnlockResponse // Internal operation response
}

Response example:

{
  "succeeded": true,
  "operation": "UNLOCK",
  "errorMessage": null,
  "operationResponse": {
    "succeeded": true,
    "errorMessage": null
  }
}