Convenzioni

Queste regole valgono su ogni endpoint, quindi vengono descritte una volta qui invece di essere ripetute su ciascuno.

Paginazione

Le collezioni sono paginate a cursore, non per scostamento. Uno scostamento è instabile su un catalogo che cambia mentre lo percorri: inserisci una scheda durante una scansione e la paginazione per scostamento ne ripete una in silenzio; cancellane una e ne salta una in silenzio. Un cursore punta a una posizione in un ordinamento stabile, quindi non succede né l'una né l'altra cosa.

# Prima pagina
GET /v1/api/properties?city=Berlin&limit=100

# Tutte le pagine successive
GET /v1/api/properties?city=Berlin&limit=100&cursor=eyJpZCI6…

Fermati quando meta.has_more è falso. Non fermarti su una pagina corta, e non calcolare un numero di pagine: non c'è un totale, deliberatamente, perché contare un grande insieme filtrato è costoso e la risposta è superata nel momento stesso in cui viene restituita.

Ogni client ha un iteratore che fa questo per te. Vedi la paginazione.

Tratta un cursore come opaco. Codifica la posizione di ordinamento e lo stato dei filtri, quindi è valido soltanto sulla stessa interrogazione, e decodificarne uno per costruirtene uno tuo non è supportato.

Tenere allineata una copia

Non rileggere un mercato a intervalli regolari. Percorrilo una volta, memorizza l'updated_at più recente che hai visto, poi chiedi soltanto ciò che è cambiato da allora:

GET /v1/api/properties?city=Berlin&updated_since=2026-08-11T04:00:00Z

Fai sovrapporre la finestra di qualche minuto invece di usare la marca temporale esatta dell'ultima passata. Le schede vengono scritte in modo concorrente, quindi un confine rigido può perdere una scheda confermata un istante dopo il tuo taglio. Trattare due volte la stessa scheda è innocuo se la tua scrittura è un upsert; perderne una no.

I webhook eliminano del tutto la necessità di questo ciclo.

Filtrare e ordinare

I filtri si combinano con un AND. Ripetere un parametro forma un OR all'interno di quel parametro, quindi ?property_type=apartment&property_type=studio significa uno dei due tipi. I filtri di intervallo usano i prefissi min_ e max_ e sono inclusivi.

Ordina con il nome di un campo, preceduto da un meno per l'ordine decrescente: ?sort=-price. L'ordinamento risolve sempre i pari merito sull'id, quindi la paginazione è deterministica anche quando molte schede condividono un prezzo. I risultati di ricerca sono ordinati per pertinenza e ignorano sort.

Campi parziali ed espansione

Due parametri modellano il contenuto in direzioni opposte. fields riduce una scheda a ciò che hai chiesto, ed expand incorpora una risorsa collegata che altrimenti sarebbe una chiamata a parte. Usati insieme di solito riducono un N+1 a un'unica richiesta:

GET /v1/api/properties?fields=id,price,living_area&expand=images

Idempotenza

Invia una Idempotency-Key su ogni POST che crea qualcosa. Un timeout di rete non ti dice nulla su se il server abbia agito, e riprovare senza una chiave è il modo in cui compaiono gli annunci duplicati.

curl -sS -X POST "https://api.skautik.com/v1/api/properties" \
  -H "Authorization: Bearer $SKAUTIK_API_KEY" \
  -H "Idempotency-Key: 6f1c2a7e-4d90-4a1b-9f33-0c2f5b8e77aa" \
  -H "Content-Type: application/json" \
  -d @property.json

Ripetere una chiave restituisce la risposta originale invece di creare una seconda scheda. Riutilizzarne una con un corpo diverso è un errore e restituisce 409. Le chiavi vengono ricordate per 24 ore. Genera un UUID per ogni creazione logica, non per ogni tentativo.

Richieste condizionali

Le letture restituiscono un ETag. Rimandalo indietro come If-None-Match e una risorsa immutata risponde 304 senza corpo, il che non ti costa quota.

Su un PATCH, invia invece l'ETag come If-Match. Se la scheda è cambiata da quando l'hai letta, la scrittura viene rifiutata con 412 invece di scartare in silenzio l'altra modifica. Rileggi, riapplica, riprova.

Formati dei dati

Identificatori di richiesta

Ogni risposta porta un'intestazione X-Request-Id, ripetuta nel corpo di qualsiasi errore. Registralo. Citarne uno permette all'assistenza di trovare la richiesta esatta invece di chiederti di riprodurre il problema.