bkapi/README.md

bkapi

A fast way to look up hamming distance hashes.

Querying

There are two interfaces for querying, both of which can be used simultaneously.

HTTP

It provides a single API endpoint, /search which takes in a hash and distance query parameter to search for matches. The response looks like this:

{
    "hash": 8525958787074004077, // Searched hash
    "distance": 3, // Maximum search distance
    "hashes": [ // Results
        {"hash": 8525958787073873005, "distance": 1}
    ]
}

NATS

It listens on $NATS_PREFIX.bkapi.search for a payload like:

[
    {"hash": 12345, "distance": 3}
]

Each input will have a corresponding entry in the response:

[
    [ // Results for first input
        {"hash": 8525958787073873005, "distance": 1}
    ]
]

Initial Load

The initial entries are populated through the database query $DATABASE_QUERY.

Listening

It can be configured to listen to PostgreSQL notifications OR with NATS messages.

PostgreSQL

It subscribes to $DATABASE_SUBSCRIBE, expecting events to be a JSON object containing the hash.

NATS

It subscribes to $NATS_PREFIX.bkapi.add, expecting events to be a JSON object containing the hash.

JetStream is used to ensure no hashes are lost without having to reload the entire tree on a connection error.