HPKV REST API

REST API

The REST API provides a simple HTTP interface for interacting with HPKV. All requests require your API key in the x-api-key header.

Base URL

Your base URL is provided when you generate an API key. All endpoints are relative to this URL.

Endpoints

1. Insert/Update/JSON Patch a Record

This endpoint supports inserting, updating, and JSON patching a record. If the record already exists, the operation will update the existing value. If the partialUpdate parameter is set to true, the operation will apply a JSON patch to the existing value or append to the existing value if it is not valid JSON.

POST /record
Content-Type: application/json
x-api-key: YOUR_API_KEY

Request Body:

{
  "key": "string",       // Required: Key to store
  "value": "string",     // Required: Value to store
  "partialUpdate": bool  // Optional: Append to existing value or apply JSON atomic patch if both values are valid JSON
}
import requests

response = requests.post(
    f"{base_url}/record",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "YOUR_API_KEY"
    },
    json={
        "key": "user:123",
        "value": "John Doe"
    }
)

JSON Atomic Patching

When using partial updates, if both the existing stored value and the new value are valid JSON objects, HPKV will automatically perform a JSON patch operation instead of simple appending. This merges the JSON objects, updating existing fields and adding new ones.

For example, if the stored value is {"name":"John","age":25} and you send a partial update with {"age":30,"city":"New York"}, the resulting value will be {"name":"John","age":30,"city":"New York"}.

If either value is not valid JSON, the system falls back to the standard append behavior.

2. Atomic Increment/Decrement

POST /record/atomic
Content-Type: application/json
x-api-key: YOUR_API_KEY

Request Body:

{
  "key": "string",      // Required: Key to increment/decrement
  "increment": number   // Required: Value to add (positive) or subtract (negative)
}

This endpoint atomically increments or decrements a numeric value stored at the specified key. If the key doesn't exist, the operation will fail with a 404 error. The response includes the new value after the operation.

response = requests.post(
    f"{base_url}/record/atomic",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "YOUR_API_KEY"
    },
    json={
        "key": "counter:123",
        "increment": 1  # Use negative value to decrement
    }
)

Response:

{
  "success": true,
  "message": "Record value incremented/decremented successfully",
  "result": 42  // The new value after increment/decrement
}

Note

Atomic operations are useful for counters, rate limiters, and other scenarios where you need to ensure consistency without race conditions. The system will automatically create the key if it doesn't exist in case of an increment.

3. Get Record

GET /record/:key
x-api-key: YOUR_API_KEY
response = requests.get(
    f"{base_url}/record/user:123",
    headers={"x-api-key": "YOUR_API_KEY"}
)

Note

When accessing records by key in the URL, make sure to URL encode the key parameter to handle special characters properly.

4. Delete Record

DELETE /record/:key
x-api-key: YOUR_API_KEY
response = requests.delete(
    f"{base_url}/record/user:123",
    headers={"x-api-key": "YOUR_API_KEY"}
)

Note

When deleting records by key in the URL, make sure to URL encode the key parameter to handle special characters properly.

5. Range Query

GET /records?startKey=<start>&endKey=<end>&limit=<limit>
x-api-key: YOUR_API_KEY

Query Parameters:

startKey  // Required: Starting key for the range (inclusive)
endKey    // Required: Ending key for the range (inclusive)
limit     // Optional: Maximum number of records to return (default: 100, max: 1000)
response = requests.get(
    f"{base_url}/records",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "startKey": "user:100",
        "endKey": "user:200",
        "limit": 50
    }
)

Note

Range queries are useful for retrieving multiple records with similar keys. For example, you can retrieve all users with IDs between 100 and 200 using a range query with startKey=user:100 and endKey=user:200.

The response includes a truncated flag that indicates whether there are more records available beyond the limit.

Make sure to URL encode the startKey and endKey parameters in the URL to handle special characters properly.

Response Formats

Success Response (GET):

{
  "key": "user:123",
  "value": "John Doe"
}

Success Response (Range Query):

{
  "records": [
    {
      "key": "user:100",
      "value": "Alice"
    },
    {
      "key": "user:101",
      "value": "Bob"
    },
    // ... more records
  ],
  "count": 50,
  "truncated": false
}

Success Response (POST/DELETE):

{
  "success": true,
  "message": "Record inserted/updated/deleted successfully"
}

Error Response:

{
  "error": "Error message"
}

Error Codes

400 Bad Request      - Invalid parameters or request body
401 Unauthorized     - Missing or invalid API key
403 Forbidden        - Permission denied
404 Not Found        - Record not found
409 Conflict         - Timestamp conflict
429 Too Many Requests - Rate limit exceeded
500 Internal Error   - Server error