Oracle-API

GET/health

Lebenszeichen des Prozesses und veröffentlichte Version.

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

Ein gesunder Prozess kann weiterhin auf Relay-Ereignisse warten oder Aktualisierungen nicht dauerhaft speichern können. Prüfe mit /ready die Bereitschaft der Datenaufnahme.

GET/ready

Momentaufnahme der Datenaufnahme: HTTP 200 bei Bereitschaft, andernfalls HTTP 503.

Bereitschaft setzt eine laufende Datenaufnahme, keinen aktuellen Datenbankfehler und ein innerhalb der letzten fünf Minuten empfangenes Follow- oder Stummschaltungsereignis voraus. Ein inaktives privates Relay kann daher 503 bewirken, obwohl der Prozess betriebsbereit ist. Beispiel beim Warten auf das erste Ereignis:

{
  "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"
}

Zeitstempel sind Unix-Sekunden; 0 bedeutet noch nicht beobachtet. persisted_events zählt akzeptierte Autoraktualisierungen, die nach der Zusammenfassung von Batches gespeichert wurden. lagged_notifications und persistence_errors zeigen Probleme der Datenaufnahme.

GET/stats

Anzahlen im indexierten Graphen, Cache-Einstellungen, Sperrmetriken und Status der Datenaufnahme.

{
  "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
  }
}

Die obigen Anzahlen und Einstellungen dienen der Veranschaulichung. edge_count zählt Follow-Kanten; mute_edge_count zählt öffentliche Stummschaltungskanten zwischen öffentlichen Schlüsseln. nodes_with_mute_lists enthält bekannte Listen ohne öffentliche Schlüsseleinträge. Sperrzeiten werden in Mikrosekunden angegeben. Das Objekt sync hat dieselben Felder wie /ready.

GET/distance

Kürzeste gerichtete Follow-Distanz von einem öffentlichen Schlüssel zu einem anderen.

• from und to: erforderliche öffentliche Schlüssel von Quelle und Ziel.
• max_hops: 1–5, Standardwert 3.
• include_bridges: boolescher Wert, standardmäßig false. Enthält verfügbare Treffpunkte der Suche.
• bypass_cache: boolescher Wert, standardmäßig false. Berechnet anhand des aktuellen indexierten Graphen neu; ruft keine neuen Relay-Daten ab.

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

hops ist bei der Distanz zu sich selbst 0 und bei einem direkten Follow eins. Der Wert null bedeutet, dass im indexierten Graphen innerhalb der angefragten Tiefe kein Pfad gefunden wurde. Er beweist nicht, dass anderswo auf Nostr keine Verbindung besteht.

path_count zählt die kürzesten gerichteten Pfade, auch wenn Brücken weggelassen werden; die Zähler sättigen beim Höchstwert einer vorzeichenlosen 64-Bit-Ganzzahl. mutual_follow bezeichnet ein direktes Follow in beiden Richtungen. Das optionale Feld bridges enthält Treffpunkte der Suche, keinen vollständigen Pfad und keinen Nachweis disjunkter Pfade.

POST/distance/batch

Fragt bis zu 100 Ziele von einer Quelle ab und erhält Reihenfolge und Duplikate der Ziele.

Erforderliche JSON-Felder: from und targets. Die optionalen Felder max_hops, include_bridges und bypass_cache verwenden dieselben Standardwerte wie /distance.

Anfrage

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

Antwort

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

Jedes Ergebnis enthält sowohl from als auch to.

GET/path

Gibt öffentliche Zwischenschlüssel auf einem kürzesten gerichteten Follow-Pfad zurück.

from und to sind erforderlich; max_hops ist optional (1–5, Standardwert 3).

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

Das Beispiel zeigt zwei Follow-Kanten: von der Quelle zur Brücke und von der Brücke zum Ziel. Quelle und Ziel sind in path nicht enthalten. Pfade zu sich selbst und direkte Follow-Pfade liefern ein leeres Array; ohne Pfad innerhalb der angefragten Tiefe wird null zurückgegeben. Diese Antwort enthält kein Feld hops.

GET/follows

Liefert die aktuell indexierte Follow-Liste eines öffentlichen Schlüssels seitenweise.

pubkey ist erforderlich; offset (Standardwert 0) und limit (Standardwert 500, höchstens 5000) sind optional. total ist die vollständige Größe der indexierten Liste, unabhängig von der Seitengröße.

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

Ein unbekannter öffentlicher Schlüssel liefert eine leere Liste und total: 0.

GET/common-follows

Gibt öffentliche Schlüssel zurück, denen beide Konten direkt folgen.

Erforderliche Parameter: from und to.

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

GET/mutes

Liefert öffentliche Schlüsseleinträge einer indexierten kind-10000-Stummschaltungsliste seitenweise.

pubkey ist erforderlich; offset (Standardwert 0) und limit (Standardwert 500, höchstens 5000) sind optional. total ist die vollständige Größe der indexierten Liste, unabhängig von der Seitengröße.

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

public_list_known: false bedeutet, dass für diesen öffentlichen Schlüssel kein Stummschaltungslisten-Ereignis indexiert wurde. Ein bekanntes Ereignis kann wie oben gezeigt keine öffentlichen Schlüsseleinträge enthalten. Verschlüsselte Stummschaltungseinträge sind für den Oracle nicht verfügbar; eine bekannte leere öffentliche Liste kann trotzdem verschlüsselte Einträge enthalten. Tags zum Stummschalten von Wörtern, Hashtags und Threads sind von den schlüsselbezogenen Indizien ausgeschlossen.

GET/trust

Gibt die Follow-Distanz zusammen mit getrennten öffentlichen Stummschaltungsbeobachtungen zurück.

• from und to: erforderliche öffentliche Schlüssel von Quelle und Ziel.
• max_hops: 1–5, Standardwert 3.
• include_bridges: boolescher Wert, standardmäßig false. Enthält verfügbare Treffpunkte der Suche.
• bypass_cache: boolescher Wert, standardmäßig false. Berechnet anhand des aktuellen indexierten Graphen neu; ruft keine neuen Relay-Daten ab.

{
  "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 listet Konten auf, denen die Quelle direkt folgt und deren indexierte öffentliche Stummschaltungslisten das Ziel enthalten. Die beiden booleschen Werte für direktes Stummschalten beschreiben die Beziehung zwischen Quelle und Ziel; die Kennzeichen für bekannte Listen unterscheiden fehlende Listen von bekannten öffentlichen Listen.

Stummschaltungen können persönliche Vorlieben ausdrücken. Fehlende öffentliche Indizien sind keine Empfehlung. Clients entscheiden, wie sie diese Beobachtungen nutzen: Die Antwort wendet weder Gewichtung noch Gesamtbewertung oder automatischen Ausschluss an. Follow-Distanz und Stummschaltungsdaten können während der Datenaufnahme zu leicht unterschiedlichen Zeitpunkten gelesen werden.