Passer au contenu principal
L’API d’Olostep est conçue autour des objets. Comprendre cette conception vous aide à créer des intégrations plus efficaces.

​
Tout est un Objet

Chaque ressource dans Olostep est un objet avec un identifiant unique. Que vous le créiez via l’API, le SDK ou le tableau de bord — vous recevez un objet que vous pouvez référencer, mettre à jour et interroger.

​
Chemins singuliers / API orientée action

Bien que nous soyons toujours prêts à défendre avec acharnement et longtemps la pureté idéologique de la conception d’une API orientée objet (un POST sur /crawls devrait créer un objet crawl, tandis qu’un GET sur /crawls/{crawl_id} devrait vous aider à récupérer cet objet et éventuellement le mettre à jour — vous pouvez toujours mettre à jour les métadonnées), chaque collection répond également à son nom singulier : POST /v1/answer se comporte exactement comme POST /v1/answers, GET /v1/scrape/{scrape_id} comme GET /v1/scrapes/{scrape_id}, et ainsi de suite pour batch, crawl, map, search, schedule, monitor, file et feedback. Le pluriel est la forme canonique et celle que cette référence documente ; le singulier est un alias pour quand vous pensez en actions plutôt qu’en objets.

​
Les Objets Peuvent Avoir des Cycles de Vie

Certains objets Olostep suivent un état via un champ status. Ce modèle de machine à états vous permet de savoir exactement où se trouve chaque ressource dans son cycle de vie.

​
Batches

Les batches ont deux niveaux de statut : le batch lui-même et les éléments individuels. Statut du Batch :
Les échecs au niveau du batch sont extrêmement rares. Les batches se terminent presque toujours — même si certaines URL échouent, le batch lui-même atteint le statut completed. Dans le cas rare d’une défaillance catastrophique de l’infrastructure (par exemple, panne du service LLM pendant l’enrichissement), le batch peut échouer. Cela affecte moins de 0,01 % des batches.
Statut de l’Élément : Chaque URL dans un batch est suivie comme un élément individuel avec son propre statut : Les éléments peuvent échouer en raison de :
  • L’URL est bloquée ou retourne une erreur
  • Sortie du parseur manquante
  • Erreurs de réseau/récupération
Les éléments échoués incluent un objet error avec code et message expliquant l’échec. Le batch se termine toujours — vérifiez le statut de chaque élément lors du traitement des résultats.

​
Crawls

Les crawls se terminent toujours. Même si un crawl trouve 0 URL (en raison du blocage par robots.txt ou d’une URL de départ invalide), le statut du crawl sera completed. Vérifiez le champ pages_count pour vérifier les résultats.

​
Monitors

Les monitors sont des objets de longue durée avec un cycle de vie plus riche que les ressources ponctuelles :
La création d’un monitor renvoie HTTP 202 avec status: provisioning. Le monitor devient active une fois que la planification résout ses cibles suivies — interrogez GET /v1/monitors/:monitor_id ou diffusez les événements de mise en service avec ?stream=1. Seuls les monitors active peuvent être mis en pause, et seuls les monitors paused peuvent être repris. Les mises à jour renvoient 409 tant que le monitor est encore en provisioning.

​
Modèle de Récupération

De nombreux objets produisent du contenu qui peut être récupéré plus tard. Le modèle retrieve_id vous permet de récupérer du contenu sans le retraiter.
Ce modèle est utilisé par :
  • Éléments de batch — Chaque URL traitée obtient un retrieve_id
  • Pages de crawl — Chaque page crawlée obtient un retrieve_id
Le point de terminaison /v1/retrieve accepte le paramètre formats pour spécifier quels types de contenu retourner (html, markdown, json, text).

​
Webhooks : Mises à Jour Pilotées par Événement

Au lieu de sonder pour les changements de statut, configurez des webhooks pour recevoir des événements lorsque les objets changent d’état.

​
Métadonnées : Vos Données à Côté des Nôtres

Attachez des paires clé-valeur personnalisées aux objets en utilisant les métadonnées. Cela vous permet de lier les ressources Olostep à vos systèmes internes.

​
Résumé