Vai al contenuto principale
L’API di Olostep è progettata attorno agli oggetti. Comprendere questo design ti aiuta a costruire integrazioni più efficaci.

​
Tutto è un Oggetto

Ogni risorsa in Olostep è un oggetto con un identificatore unico. Che tu lo crei tramite l’API, l’SDK o la dashboard — ottieni un oggetto che puoi referenziare, aggiornare e interrogare.

​
Percorsi singolari / API orientata all’azione

Sebbene siamo sempre pronti a combattere duramente e a lungo sulla purezza ideologica del design dell’API orientata agli oggetti (un POST su /crawls dovrebbe creare un oggetto crawl, mentre un GET su /crawls/{crawl_id} dovrebbe aiutarti a recuperare quell’oggetto e possibilmente aggiornarlo — puoi sempre aggiornare i metadati), ogni collezione risponde anche al suo nome singolare: POST /v1/answer si comporta esattamente come POST /v1/answers, GET /v1/scrape/{scrape_id} come GET /v1/scrapes/{scrape_id}, e così via per batch, crawl, map, search, schedule, monitor, file e feedback. Il plurale è la forma canonica e quella documentata in questo riferimento; il singolare è un alias per quando pensi in termini di azioni piuttosto che di oggetti.

​
Gli Oggetti Possono Avere Cicli di Vita

Alcuni oggetti di Olostep tracciano lo stato tramite un campo status. Questo schema a macchina a stati ti permette di sapere esattamente dove si trova ogni risorsa nel suo ciclo di vita.

​
Batch

I batch hanno due livelli di stato: il batch stesso e i singoli elementi. Stato del Batch:
I fallimenti a livello di batch sono estremamente rari. I batch quasi sempre si completano — anche se alcuni URL falliscono, il batch stesso raggiunge lo stato completed. In caso raro di un fallimento catastrofico dell’infrastruttura (es. interruzione del servizio LLM durante l’arricchimento), il batch potrebbe fallire. Questo colpisce meno dello 0,01% dei batch.
Stato degli Elementi: Ogni URL in un batch è tracciato come un elemento individuale con il proprio stato: Gli elementi possono fallire a causa di:
  • URL bloccato o che restituisce un errore
  • Output del parser mancante
  • Errori di rete/fetch
Gli elementi falliti includono un oggetto error con code e message che spiegano il fallimento. Il batch si completa comunque — controlla lo stato di ogni elemento quando elabori i risultati.

​
Crawl

I crawl si completano sempre. Anche se un crawl trova 0 URL (a causa del blocco di robots.txt o URL di partenza non valido), lo stato del crawl sarà completed. Controlla il campo pages_count per verificare i risultati.

​
Monitor

I monitor sono oggetti di lunga durata con un ciclo di vita più ricco rispetto alle risorse one-shot:
Creare un monitor restituisce HTTP 202 con status: provisioning. Il monitor diventa active una volta che la pianificazione risolve i suoi obiettivi tracciati — interroga GET /v1/monitors/:monitor_id o trasmetti eventi di provisioning con ?stream=1. Solo i monitor active possono essere messi in pausa, e solo i monitor paused possono essere ripresi. Gli aggiornamenti restituiscono 409 mentre il monitor è ancora in provisioning.

​
Modello di Recupero

Molti oggetti producono contenuti che possono essere recuperati successivamente. Il modello retrieve_id ti permette di ottenere contenuti senza ri-elaborarli.
Questo modello è utilizzato da:
  • Elementi del batch — Ogni URL elaborato ottiene un retrieve_id
  • Pagine del crawl — Ogni pagina scrappata ottiene un retrieve_id
L’endpoint /v1/retrieve accetta il parametro formats per specificare quali tipi di contenuto restituire (html, markdown, json, text).

​
Webhook: Aggiornamenti Basati su Eventi

Invece di interrogare per i cambiamenti di stato, configura i webhook per ricevere eventi quando gli oggetti cambiano stato.

​
Metadati: I Tuoi Dati Accanto ai Nostri

Allega coppie chiave-valore personalizzate agli oggetti usando i metadati. Questo ti permette di collegare le risorse di Olostep ai tuoi sistemi interni.