Pagination
Les collections acceptent généralement limit et un curseur comme before ou after. Considérez le curseur comme opaque, conservez l’ordre serveur, arrêtez-vous lorsque la page contient moins d’éléments que demandé et dédupliquez les ID si les données peuvent changer pendant le parcours. Consultez le schéma interactif car les directions disponibles diffèrent selon les collections.
GET /api/v1/channels/<channel_id>/messages?limit=50&before=<message_id>
Authorization: Bot <token>Erreurs, tentatives et limites de débit
Les erreurs utilisent { error: { code, message } }. Conservez le statut HTTP, le code et X-Request-ID dans les journaux. Ne relancez les erreurs réseau, 429 et certains 5xx que pour une opération idempotente ou protégée par une clé d’idempotence applicative.
| Réponse | Action du client |
|---|---|
| 400 / 422 | Corriger la saisie, sans nouvelle tentative automatique |
| 401 | Rafraîchir la session humaine ou renouveler les identifiants |
| 403 | Vérifier l’appartenance, le rôle et les permissions du salon |
| 404 | Considérer la ressource absente ; certaines ressources privées sont masquées |
| 409 | Relire l’état courant avant de décider |
| 429 | Attendre Retry-After puis ajouter un léger aléa |
| 5xx | Utiliser un backoff exponentiel borné et rendre visible l’échec persistant |
Versions et compatibilité
Le préfixe REST stable est /api/v1. Pendant la bêta, des champs de réponse, valeurs d’enum et événements Gateway peuvent être ajoutés sans changement de version. Les clients doivent ignorer l’inconnu. Retirer un champ, changer son sens ou restreindre une entrée exige une migration documentée et une nouvelle version API ou une fenêtre de compatibilité annoncée.
OpenAPI est le contrat machine
Épinglez le contrat téléchargé lors de la génération de clients et relisez son diff avant une mise à niveau. La CI empêche la dérive des routes, mais le consommateur choisit quand adopter un nouveau contrat.
Dépréciations et migrations
- Une opération dépréciée reste documentée avec son remplacement et sa date de retrait
- Un retrait de sécurité peut être accéléré en cas de risque matériel
- Les changelogs des SDK suivent le versionnement sémantique et signalent les migrations
- Testez sur un nœud de préproduction avant de changer les identifiants ou intents Gateway
Checklist de sécurité
- Conserver les jetons Bot et webhook dans un gestionnaire de secrets
- Utiliser HTTPS et WSS hors localhost
- Ne jamais envoyer Authorization: Bot vers une URL protégée par un jeton de webhook
- Valider les identifiants des interactions et callbacks avant d’agir
- Masquer les jetons, contenus et données personnelles dans les diagnostics
- Renouveler les identifiants après toute exposition présumée et vérifier le rejet de l’ancien jeton