API Oracle

GET/health

Stato di esecuzione del processo e versione rilasciata.

{
  "status": "healthy",
  "version": "0.3.0"
}

Un processo funzionante può ancora essere in attesa di eventi dai relay o non riuscire a salvare gli aggiornamenti. Usa /ready per verificare se l’acquisizione è pronta.

GET/ready

Stato dell’acquisizione: HTTP 200 quando è pronta, HTTP 503 altrimenti.

Lo stato pronto richiede acquisizione in esecuzione, nessun errore attuale del database e un evento di follow o silenziamento ricevuto negli ultimi cinque minuti. Un relay privato poco attivo può quindi restituire 503 anche quando il processo è operativo. Esempio in attesa del primo evento:

{
  "running": true,
  "ready": false,
  "last_event_received_at": 0,
  "last_persisted_at": 0,
  "persisted_events": 0,
  "lagged_notifications": 0,
  "persistence_errors": 0,
  "coverage": "configured_relays_only"
}

I timestamp sono espressi in secondi Unix; zero significa che non è ancora avvenuta alcuna osservazione. persisted_events conta gli aggiornamenti degli autori accettati e salvati dopo il consolidamento dei lotti. lagged_notifications e persistence_errors segnalano problemi di acquisizione.

GET/stats

Conteggi del grafo indicizzato, impostazioni della cache, metriche dei blocchi e stato dell’acquisizione.

{
  "node_count": 3,
  "edge_count": 2,
  "nodes_with_follows": 2,
  "mute_edge_count": 0,
  "nodes_with_mute_lists": 1,
  "sync": {
    "running": true,
    "ready": false,
    "last_event_received_at": 0,
    "last_persisted_at": 0,
    "persisted_events": 0,
    "lagged_notifications": 0,
    "persistence_errors": 0,
    "coverage": "configured_relays_only"
  },
  "cache": {
    "size": 0,
    "capacity": 100000,
    "ttl_secs": 300
  },
  "locks": {
    "write_lock_count": 0,
    "write_lock_avg_us": 0,
    "write_lock_max_us": 0,
    "read_lock_count": 0,
    "read_lock_avg_us": 0,
    "read_lock_max_us": 0
  }
}

I conteggi e le impostazioni sopra sono illustrativi. edge_count conta gli archi di follow; mute_edge_count conta gli archi pubblici di silenziamento delle chiavi pubbliche. nodes_with_mute_lists include liste note senza voci pubbliche di chiavi pubbliche. I tempi dei blocchi sono in microsecondi. L’oggetto sync ha gli stessi campi di /ready.

GET/distance

Distanza minima direzionale di follow tra due chiavi pubbliche.

• from e to: chiavi pubbliche di origine e destinazione obbligatorie.
• max_hops: da 1 a 5, valore predefinito 3.
• include_bridges: booleano, false per impostazione predefinita. Include i nodi di incontro della ricerca quando disponibili.
• bypass_cache: booleano, false per impostazione predefinita. Ricalcola dal grafo attualmente indicizzato; non recupera nuovi dati dai relay.

{
  "from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "to": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "hops": 2,
  "path_count": 1,
  "mutual_follow": false
}

hops è zero per la distanza da sé stessi e uno per un follow diretto. Un valore null significa che non è stato trovato un percorso entro la profondità richiesta nel grafo indicizzato. Non dimostra che non esista una connessione altrove su Nostr.

path_count conta i percorsi direzionali più brevi, anche quando i ponti sono omessi; il conteggio satura al massimo intero senza segno a 64 bit. mutual_follow indica un follow diretto in entrambe le direzioni. Il campo facoltativo bridges contiene i nodi di incontro della ricerca, non un percorso completo né una prova di percorsi disgiunti.

POST/distance/batch

Interrogare fino a 100 destinazioni da un’origine, mantenendo ordine e duplicati delle destinazioni.

Campi JSON obbligatori: from e targets. I campi facoltativi max_hops, include_bridges e bypass_cache usano gli stessi valori predefiniti di /distance.

Richiesta

{
  "from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "targets": [
    "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
  ],
  "max_hops": 3
}

Risposta

{
  "from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "results": [
    {
      "from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "to": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "hops": 2,
      "path_count": 1,
      "mutual_follow": false
    }
  ]
}

Ogni risultato include sia from sia to.

GET/path

Restituire le chiavi pubbliche intermedie lungo uno dei percorsi direzionali di follow più brevi.

from e to obbligatori; max_hops facoltativo (da 1 a 5, predefinito 3).

{
  "from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "to": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "path": [
    "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
  ]
}

L’esempio rappresenta due archi di follow, dall’origine al ponte e poi alla destinazione. Origine e destinazione sono escluse da path. I percorsi verso sé stessi e i follow diretti restituiscono un array vuoto; l’assenza di un percorso entro la profondità richiesta restituisce null. Questa risposta non contiene il campo hops.

GET/follows

Paginare la lista dei follow attualmente indicizzata per una chiave pubblica.

pubkey obbligatorio; offset (predefinito 0) e limit (predefinito 500, massimo 5000) facoltativi. total indica la dimensione completa della lista indicizzata, indipendentemente dalla dimensione della pagina.

{
  "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "follows": [
    "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
  ],
  "total": 1
}

Una chiave pubblica sconosciuta restituisce una lista vuota e total: 0.

GET/common-follows

Restituire le chiavi pubbliche seguite direttamente da entrambi gli account.

Parametri obbligatori: from e to.

{
  "from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "to": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "common_follows": [
    "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
  ]
}

GET/mutes

Paginare le voci pubbliche di chiavi pubbliche di una lista di silenziamento indicizzata di tipo 10000.

pubkey obbligatorio; offset (predefinito 0) e limit (predefinito 500, massimo 5000) facoltativi. total indica la dimensione completa della lista indicizzata, indipendentemente dalla dimensione della pagina.

{
  "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "mutes": [],
  "total": 0,
  "public_list_known": true
}

public_list_known: false significa che per questa chiave pubblica non è stato indicizzato alcun evento di lista di silenziamento. Un evento noto può non avere voci pubbliche di chiavi pubbliche, come mostrato sopra. Le voci cifrate non sono accessibili a Oracle e una lista pubblica nota e vuota può comunque contenere voci cifrate. I tag di silenziamento di parole, hashtag e discussioni sono esclusi dalle osservazioni sulle chiavi pubbliche.

GET/trust

Restituire la distanza di follow insieme a osservazioni pubbliche separate sui silenziamenti.

• from e to: chiavi pubbliche di origine e destinazione obbligatorie.
• max_hops: da 1 a 5, valore predefinito 3.
• include_bridges: booleano, false per impostazione predefinita. Include i nodi di incontro della ricerca quando disponibili.
• bypass_cache: booleano, false per impostazione predefinita. Ricalcola dal grafo attualmente indicizzato; non recupera nuovi dati dai relay.

{
  "follow_distance": {
    "from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "to": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "hops": 2,
    "path_count": 1,
    "mutual_follow": false
  },
  "public_mute_evidence": {
    "source_mutes_target": false,
    "target_mutes_source": false,
    "followed_muters": [
      "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
    ],
    "source_mute_list_known": true,
    "target_mute_list_known": false
  }
}

followed_muters elenca gli account seguiti direttamente dall’origine le cui liste pubbliche di silenziamento indicizzate contengono la destinazione. I due booleani di silenziamento diretto descrivono la relazione tra origine e destinazione; gli indicatori di lista nota distinguono le liste mancanti da quelle pubbliche note.

I silenziamenti possono esprimere preferenze personali. L’assenza di osservazioni pubbliche non costituisce una raccomandazione. I client decidono come usare queste osservazioni: la risposta non applica pesi, punteggi aggregati o esclusioni automatiche. La distanza di follow e le osservazioni sui silenziamenti possono essere lette in istanti leggermente diversi durante l’acquisizione.