De API van Olostep is ontworpen rond objecten. Door dit ontwerp te begrijpen, kun je effectievere integraties bouwen. Dit ontwerp is geïnspireerd door Stripe’s API-filosofie.
Alles is een Object
Elke bron in Olostep is een object met een unieke identificatie. Of je het nu creëert via de API, SDK of dashboard — je krijgt een object terug dat je kunt refereren, bijwerken en opvragen.
| Bron | Object ID Formaat | Voorbeeld |
|---|
| Scrape | scrape_* | scrape_abc123 |
| Batch | batch_* | batch_xyz789 |
| Crawl | crawl_* | crawl_def456 |
| Map | map_* | map_ghi012 |
| Answer | answer_* | answer_jkl345 |
| File | file_* | file_mno678 |
| Schedule | schedule_* | schedule_pqr901 |
Objecten Kunnen Levenscycli Hebben
Sommige Olostep-objecten volgen de status via een status veld. Dit toestandsmachinepatroon laat je precies weten waar elke bron zich in zijn levenscyclus bevindt.
Batches
Batches hebben twee niveaus van status: de batch zelf en individuele items.
Batch Status:
| Status | Beschrijving |
|---|
in_progress | URL’s worden gescraped |
completed | Verwerking voltooid |
Batch-niveau fouten zijn uiterst zeldzaam. Batches worden bijna altijd voltooid — zelfs als sommige URL’s falen, bereikt de batch zelf de status completed. In het zeldzame geval van een catastrofale infrastructuurfout (bijv. LLM-service uitval tijdens verrijking), kan de batch falen. Dit treft minder dan 0,01% van de batches.
| Status | Beschrijving |
|---|
success | URL succesvol gescraped |
failed | URL kon niet worden gescraped |
- URL is geblokkeerd of geeft een fout terug
- Parser uitvoer ontbreekt
- Netwerk-/fetchfouten
Mislukte items bevatten een error object met code en message die de fout uitleggen. De batch wordt nog steeds voltooid — controleer de status van elk item bij het verwerken van resultaten.
Crawls
| Status | Beschrijving |
|---|
in_progress | Actief ontdekken en verwerken van URL’s |
completed | Crawlen voltooid |
Crawls worden altijd voltooid. Zelfs als een crawl 0 URL’s vindt (door robots.txt blokkering of ongeldige start-URL), zal de crawlstatus completed zijn. Controleer het pages_count veld om resultaten te verifiëren.
Ophaalpatroon
Veel objecten produceren inhoud die later kan worden opgehaald. Het retrieve_id patroon laat je inhoud ophalen zonder opnieuw te verwerken.
# Haal inhoud op met retrieve_id
curl "https://api.olostep.com/v1/retrieve?retrieve_id=6h89o8u1kt" \
-H "Authorization: Bearer <your_token>"
- Batch items — Elke verwerkte URL krijgt een
retrieve_id
- Crawl pagina’s — Elke gecrawlde pagina krijgt een
retrieve_id
De /v1/retrieve endpoint accepteert de formats parameter om te specificeren welke inhoudstypen moeten worden geretourneerd (html, markdown, json, text).
Webhooks: Gebeurtenisgestuurde Updates
In plaats van te polleren voor statuswijzigingen, configureer webhooks om gebeurtenissen te ontvangen wanneer objecten van status veranderen.
{
"event": "batch.completed",
"data": {
"id": "batch_xyz789",
"status": "completed",
"items_total": 100,
"items_completed": 100
}
}
Voeg aangepaste sleutel-waardeparen toe aan objecten met behulp van metadata. Hiermee kun je Olostep-bronnen koppelen aan je interne systemen.
{
"items": [{"url": "https://example.com"}],
"metadata": {
"order_id": "12345",
"customer": "acme-corp"
}
}
Samenvatting
| Concept | Beschrijving |
|---|
| Objecten | Elke bron heeft een unieke ID en is opvraagbaar |
| Levenscycli | Volg voortgang via status veld |
| Ophalen | Haal later inhoud op met retrieve_id |
| Webhooks | Wordt op de hoogte gebracht bij statuswijzigingen |
| Metadata | Voeg je eigen gegevens toe aan elk object |
