Docs/Long Polling

Long Polling

Utilisez le long polling lorsque votre serveur ne peut pas recevoir de requêtes webhook entrantes — par exemple, en développement local ou derrière un pare-feu restrictif.

Quand utiliser le long polling

✓

Serveur derrière un pare-feu ou NAT (pas d'URL publique)

✓

Hébergement mutualisé qui bloque les webhooks entrants

✓

Hébergement avec des limites restrictives de taille d'envoi (puisque vous récupérez les images au lieu de les recevoir)

✓

Développement local sans tunnelisation (ngrok, etc.)

✓

Environnements serverless avec des délais d'exécution courts

✓

Lorsque vous devez traiter les images à votre propre rythme

Note pour la production

Pour une utilisation en production, les webhooks sont recommandés. Le long polling nécessite que votre serveur maintienne une boucle d'interrogation continue et acquitte chaque image individuellement.

Points de terminaison

GET/api/v1/sessions/:id/poll

Effectue un long polling pour obtenir la prochaine image non acquittée. Le serveur maintient la connexion ouverte pendant un maximum de 30 secondes. Si une image devient disponible, elle est retournée immédiatement. Si aucune image n'arrive dans les 30 secondes, le serveur retourne une réponse 204 No Content.

Paramètres de requête

ParamètreTypeDescription
timeoutintegerNombre maximal de secondes d'attente. Par défaut 30, maximum 30.
GET/api/v1/images/:imageId/download

Télécharge les octets bruts de l'image. Retourne l'image avec le Content-Type approprié.

POST/api/v1/images/:imageId/ack

Acquitte que votre serveur a bien reçu et traité l'image. Les images non acquittées seront retournées lors de la prochaine requête de polling. L'acquittement doit être effectué dans les 5 minutes suivant la réception de l'image.

Exemple de boucle de polling

# Single poll request (returns 200 with image info, 204 if nothing, 410 if done)
curl -H "Authorization: Bearer aptr_xxxx" \
  "https://api.apertur.ca/v1/sessions/sess_01HX.../poll?timeout=30"

# Download an image
curl -H "Authorization: Bearer aptr_xxxx" \
  -o photo.jpg \
  "https://api.apertur.ca/v1/images/img_01HX.../download"

# Acknowledge an image
curl -X POST -H "Authorization: Bearer aptr_xxxx" \
  "https://api.apertur.ca/v1/images/img_01HX.../ack"

Format de la réponse de polling

{
  "image_id": "img_01HX...",
  "image_index": 0,
  "filename": "photo.jpg",
  "mime_type": "image/jpeg",
  "size_bytes": 245000,
  "session_status": "uploading",
  "tags": {
    "user_id": "usr_abc123"
  }
}

Téléchargez les octets de l'image en utilisant GET /api/v1/images/:imageId/download.

← WebhooksSuivant : Erreurs →