Paginer l'API Web de Slack et gérer les paliers de limitation de débit par méthode

Ce que c'est

Le guide de pagination de Slack explique que les méthodes paginées par curseur « acceptent les paramètres cursor et limit » et que « les réponses paginées incluent un objet response_metadata de premier niveau, qui contient un next_cursor lorsqu'il reste des résultats à récupérer ». Le client renvoie cette valeur dans le paramètre cursor de l'appel suivant. Un next_cursor vide, null ou absent indique qu'il n'y a plus de résultats ; le guide met explicitement en garde contre le fait de déduire que la récupération est terminée à partir du nombre de résultats. Les curseurs expirent : il ne faut pas conserver de curseurs pendant des heures ou des jours, et un curseur périmé ou corrompu renvoie invalid_cursor. Le maximum de limit est de 1000, valeur « susceptible de changer et pouvant varier selon la méthode » ; 100 à 200 est recommandé pour une pagination respectueuse du service. La page des limites de débit de Slack répartit les méthodes en paliers (tiers), d'environ « 1+ par minute » (Tier 1) jusqu'à « 100+ par minute » (Tier 4), auxquels s'ajoutent des règles de « Special Tier » propres à certaines méthodes, par exemple chat.postMessage, qui autorise en général environ un message par seconde et par canal. Toutes ces limites s'appliquent « par méthode d'API, par espace de travail (équipe) et par application ». Sur toute API HTTP, y compris les webhooks entrants, le dépassement d'une limite renvoie « HTTP 429 Too Many Requests » accompagné d'un en-tête HTTP Retry-After contenant le nombre de secondes à attendre avant de réessayer. Cette restriction est limitée à la méthode et à l'espace de travail concernés ; les autres méthodes et les autres espaces de travail ne sont pas touchés.

Pourquoi c'est important

Avec ces paliers, un même client peut rester largement dans son budget sur une méthode et être immédiatement limité sur une autre. Considérer que l'API a une seule limite de débit globale conduit à une limitation insuffisante ou excessive des appels. La documentation indique aussi que récupérer une très grande liste d'un seul bloc, sans pagination, entraîne en soi des limites plus strictes.

Comment l'appliquer

• Toujours envoyer limit explicitement et vérifier response_metadata.next_cursor après chaque appel, en bouclant jusqu'à ce qu'il soit vide ou absent.
• Suivre les budgets par méthode et non globalement, car les paliers et les limites particulières (comme la publication de messages) dépendent de la méthode.
• Sur un 429, lire Retry-After et attendre exactement ce délai avant de rappeler la même méthode pour cet espace de travail ; les autres méthodes restent utilisables entre-temps.
• Pour les exports en masse (par exemple tous les utilisateurs ou tous les canaux), paginer avec un limit modéré (100 à 200) plutôt que de demander le maximum en un seul appel.

def list_all_users(client, limit=200):
    cursor, users = None, []
    while True:
        resp = client.users_list(limit=limit, cursor=cursor)
        users += resp["members"]
        cursor = resp.get("response_metadata", {}).get("next_cursor")
        if not cursor:
            return users

Pièges

Arrêter la pagination dès qu'une page renvoie moins de résultats que limit : la documentation de Slack qualifie explicitement ce critère de signal peu fiable de fin de liste. Appliquer un seul budget de nouvelles tentatives et de backoff à toutes les méthodes de l'API Web, au lieu d'un budget par méthode et par espace de travail, comme l'exigent les paliers.