/api/drd/user/search

GET

Searches the Distributed Resource Directory by name. Open read — no authentication. Matching is a case-insensitive prefix match on either or both names. Results from all responding RAIDA servers are merged by (denomination, serial number) with the newest updated_at winning, so one directory entry appears once even when 25 servers return it.

http://localhost:8080/api/drd/user/search?first_name=Ali&limit=10

Parameters

Name Type Required Description
first_name string No* First-name prefix to match, at most 63 bytes. *At least one of first_name / last_name is required.
last_name string No* Last-name prefix to match, at most 63 bytes.
limit integer No Maximum results per server, 1-50. 0 or omitted = server maximum (50).
wallet_path string No Wallet used to pick the request-encryption coin. Defaults to the Default wallet.

Responses

Success Response (200)

The fan-out fields are shared by every DRD endpoint: pass_count / fail_count / no_response_count total 25, quorum is true when 13 or more RAIDA servers accepted, and raida_results holds one entry per server (25 entries; truncated in the examples below). Status 250 is success; failed entries include an error string.

{
    "command": "drd-user-search",
    "success": true,
    "count": 1,
    "users": [
        {
            "denomination": 1,
            "serial_number": 9840,
            "inbox_fee": "0.5",
            "inbox_fee_units": 50000000,
            "first_symbol": 3,
            "second_symbol": 14,
            "class_rejection": 0,
            "created_at": 1783741315,
            "updated_at": 1783741315,
            "account_age_seconds": 86400,
            "first_name": "Alice",
            "last_name": "Example"
        }
    ],
    "pass_count": 25,
    "fail_count": 0,
    "no_response_count": 0,
    "quorum": true,
    "raida_results": [
        { "raida": 0, "success": true, "status": 250 },
        { "raida": 1, "success": true, "status": 250 }
    ]
}

Error Responses

400 Bad Request

Neither name given, or a name longer than 63 bytes.

{
    "error": true,
    "message": "Give at least one of first_name, last_name (prefix match)",
    "code": 400
}

502 Bad Gateway

No RAIDA server accepted the request. The body names the dominant failure status and includes the full per-server detail.

{
    "error": true,
    "message": "No RAIDA answered the search",
    "code": 502,
    "raida_status_code": 200,
    "detail": "Invalid AN",
    "pass_count": 0,
    "fail_count": 25,
    "no_response_count": 0,
    "quorum": false,
    "raida_results": [
        { "raida": 0, "success": false, "status": 200, "error": "Invalid AN" }
    ]
}

Examples

cURL Example

curl -X GET "http://localhost:8080/api/drd/user/search?first_name=Ali&limit=10"

JavaScript Example

fetch(`http://localhost:8080/api/drd/user/search?first_name=Ali&limit=10`)
    .then(r => r.json())
    .then(data => {
        if (data.success) {
            data.users.forEach(u =>
                console.log(`${u.first_name} ${u.last_name} (DN${u.denomination}.${u.serial_number})`));
        }
    });

Python Example

import requests

url = 'http://localhost:8080/api/drd/user/search'
data = requests.get(url, params={'first_name': 'Ali', 'limit': 10}).json()

for u in data.get('users', []):
    print(f"{u['first_name']} {u['last_name']} — DN{u['denomination']}.{u['serial_number']}")

Notes

  • Requests fan out to all 25 RAIDA servers in parallel; the client owns consistency. On partial success (pass_count < 25), re-issue the same request to bring stragglers up to date.
  • Prefix match only, case-insensitive; %, _ and \ in the search text are treated as literal characters.
  • An empty result set is still a 200 with count: 0.
  • Results are capped at 50 per server; narrow the prefix if you hit the cap.