Zum Hauptinhalt springen
Die API von Olostep ist um Objekte herum gestaltet. Dieses Design zu verstehen, hilft dir, effektivere Integrationen zu erstellen.

​
Alles ist ein Objekt

Jede Ressource in Olostep ist ein Objekt mit einem eindeutigen Bezeichner. Egal, ob du es über die API, das SDK oder das Dashboard erstellst – du erhältst ein Objekt zurück, auf das du verweisen, das du aktualisieren und abfragen kannst.

​
Singularpfade / Aktionsorientierte API

Obwohl wir bereit sind, hart und lange über die ideologische Reinheit des objektorientierten API-Designs zu kämpfen (ein POST auf /crawls sollte ein crawl-Objekt erstellen, während ein GET auf /crawls/{crawl_id} dir helfen sollte, dieses Objekt abzurufen und möglicherweise zu aktualisieren – du kannst immer Metadaten aktualisieren), antwortet jede Sammlung auch auf ihren Singularnamen: POST /v1/answer verhält sich genau wie POST /v1/answers, GET /v1/scrape/{scrape_id} wie GET /v1/scrapes/{scrape_id}, und so weiter für batch, crawl, map, search, schedule, monitor, file und feedback. Der Plural ist die kanonische Form und die, die in diesem Referenzdokument beschrieben wird; der Singular ist ein Alias, wenn du in Aktionen statt in Objekten denkst.

​
Objekte können Lebenszyklen haben

Einige Olostep-Objekte verfolgen den Status über ein status-Feld. Dieses Zustandsmaschinenmuster lässt dich genau wissen, wo sich jede Ressource in ihrem Lebenszyklus befindet.

​
Batches

Batches haben zwei Status-Ebenen: den Batch selbst und die einzelnen Items. Batch-Status:
Batch-Level-Fehler sind extrem selten. Batches werden fast immer abgeschlossen – auch wenn einige URLs fehlschlagen, erreicht der Batch selbst den Status completed. Im seltenen Fall eines katastrophalen Infrastrukturfehlers (z.B. LLM-Dienstunterbrechung während der Anreicherung) kann der Batch fehlschlagen. Dies betrifft weniger als 0,01% der Batches.
Item-Status: Jede URL in einem Batch wird als einzelnes Item mit eigenem Status verfolgt: Items können aus folgenden Gründen fehlschlagen:
  • URL ist blockiert oder gibt einen Fehler zurück
  • Parser-Ausgabe fehlt
  • Netzwerk-/Abruffehler
Fehlgeschlagene Items enthalten ein error-Objekt mit code und message, das den Fehler erklärt. Der Batch wird dennoch abgeschlossen – überprüfe den Status jedes Items bei der Verarbeitung der Ergebnisse.

​
Crawls

Crawls werden immer abgeschlossen. Selbst wenn ein Crawl 0 URLs findet (aufgrund von robots.txt-Blockierung oder ungültiger Start-URL), wird der Crawl-Status completed sein. Überprüfe das pages_count-Feld, um die Ergebnisse zu verifizieren.

​
Monitore

Monitore sind langlebige Objekte mit einem reicheren Lebenszyklus als Einmalressourcen:
Das Erstellen eines Monitors gibt HTTP 202 mit status: provisioning zurück. Der Monitor wird active, sobald die Planung seine verfolgten Ziele auflöst – poll GET /v1/monitors/:monitor_id oder streame Bereitstellungsereignisse mit ?stream=1. Nur active-Monitore können pausiert und nur paused-Monitore können fortgesetzt werden. Updates geben 409 zurück, während der Monitor noch provisioning ist.

​
Abrufmuster

Viele Objekte erzeugen Inhalte, die später abgerufen werden können. Das retrieve_id-Muster ermöglicht es dir, Inhalte abzurufen, ohne sie erneut zu verarbeiten.
Dieses Muster wird verwendet von:
  • Batch-Items — Jede verarbeitete URL erhält eine retrieve_id
  • Crawl-Seiten — Jede gecrawlte Seite erhält eine retrieve_id
Der /v1/retrieve-Endpunkt akzeptiert den formats-Parameter, um anzugeben, welche Inhaltstypen zurückgegeben werden sollen (html, markdown, json, text).

​
Webhooks: Ereignisgesteuerte Updates

Anstatt auf Statusänderungen zu warten, konfiguriere Webhooks, um Ereignisse zu erhalten, wenn Objekte ihren Status ändern.

​
Metadaten: Deine Daten neben unseren

Füge benutzerdefinierte Schlüssel-Wert-Paare zu Objekten hinzu, indem du Metadaten verwendest. Dadurch kannst du Olostep-Ressourcen mit deinen internen Systemen verknüpfen.

​
Zusammenfassung