Présentation étape par étape d'une intégration d'API côté serveur de base

Ce guide explique comment mettre en place une intégration API de base côté serveur.

Cela permettra de vérifier que l'utilisateur de votre site web est autorisé à accéder à l'URL actuelle et, dans le cas contraire, de le rediriger vers une salle d'attente.

Ce guide s'adresse aux développeurs. Il suppose que le lecteur maîtrise les API, etc.

Cette intégration utilise les ressources publiques de l'API CrowdHandler, via la clé publique. Elle est disponible pour tous les forfaits, y compris la formule gratuite.

1. Connexion à l'API

Vous aurez tout d'abord besoin de votre clé publique. Consultez notre présentation de l'API pour obtenir votre clé API.

2. Passer votre premier appel

POST /requests/

Nous utilisons ici Postman pour illustrer ces appels. C'est un excellent moyen d'effectuer des appels API, de tester l'envoi de paramètres et de comprendre les réponses obtenues au fur et à mesure que vous mettez en place votre intégration.

Nous utilisons l'authentification de base pour envoyer notre clé. Postman nous permet de la saisir une seule fois dans l'onglet « Autorisation » et de l'enregistrer pour tous les appels que nous effectuons. La clé doit être saisie dans le champ « Nom d'utilisateur ». Le champ « Mot de passe » est ignoré.

Maintenant que notre en-tête d'authentification est configuré, nous allons commencer par effectuer un appel POST vers https://api.crowdhandler.com/v1/requests. Cet appel sert à lancer une nouvelle requête vers une URL de votre site, afin de déterminer si cet utilisateur doit obtenir l'accès ou être redirigé.

L'appel POST attend la charge utile JSON suivante :

{
    "url": "https://test.crowdhandler.com/some-url",
    "ip": "127.0.0.1",
    "agent": "Just testing",
    "lang": "Just testing"
}

Passons en revue ces paramètres :

  • url - Il s'agit de l'URL à laquelle votre utilisateur tente d'accéder. La manière dont vous l'obtenez dépend de votre application, de votre langage de programmation et de votre framework. Il peut s'agir d'une variable CGI, ou bien vous pouvez disposer d'un contrôleur frontal ou d'un routeur. L'URL doit être complète, protocole compris. CrowdHandler ne prend en charge que le protocole HTTPS.
  • ip - Il s'agit de l'adresse IP associée à la requête de l'utilisateur. Là encore, la source à partir de laquelle vous récupérez cette information dépendra de votre langage de programmation et de votre framework. L'adresse IP est obligatoire. Elle sert à prévenir la fraude et à détecter les robots.
  • agent - il s'agit de la chaîne d'agent utilisateur. Ce champ est également obligatoire. Vous devez la récupérer à partir de l'en-tête HTTP « User-Agent ».
  • lang - il s'agit de la langue préférée de l'utilisateur. Ce paramètre est facultatif et peut aider à identifier les agents frauduleux. Vous pouvez l'obtenir à partir de l'en-tête HTTP « Accept-Language ».

Si tout se passe bien et que l'URL que vous avez fournie est protégée par une « salle d'attente », vous devriez recevoir une réponse qui ressemblera à peu près à ceci :

{
    "result": {
        "status": 1,
        "token": "tok_6ihQ7XNw0GmS",
        "title": "Queen Victoria Hall",
        "position": 648,
        "promoted": 0,
        "urlRedirect": null,
        "onsale": "2020-10-21T15:11:11Z",
        "message": "Our website is very busy right now. Sorry to keep you waiting, we will redirect you as soon as possible.",
        "slug": "queen-victoria-hall",
        "priority": null,
        "priorityAvailable": 0,
        "logo": null,
        "responseID": "1dc0784ea988c4139f406061f39edd39",
        "ttl": 0
    }
}

Parcourir les résultats :

  • Un « token » est l'identifiant de l'utilisateur. Comme nous n'en avions pas au départ, nous avons effectué une requête POST, qui n'en nécessite pas, ce qui signifie que nous avons reçu un nouveau token dès notre première requête.
  • La valeur « promoted » est la principale caractéristique qui nous intéresse. Une valeur de 0 signifie que l'utilisateur associé à ce jeton doit passer par la file d'attente pour l'URL indiquée. Une valeur de 1 signifie que l'utilisateur n'a pas besoin de passer par la file d'attente. Ce jeton a une valeur « promoted » égale à 0, ce qui indique que cet utilisateur doit passer par la file d'attente.
  • slug: le slug indique l'adresse de la salle d'attente. L'adresse complète de la salle d'attente sera https://wait.crowdhandler.com/your-slug
  • responseID est un identifiant unique qui identifie la réponse que vous venez de recevoir. Nous pourrions l'utiliser ultérieurement pour enregistrer les performances de cette requête via l'API CrowdHandler.
  • Les autres attributs sont intéressants et peuvent faciliter le dépannage et le débogage, mais vous n'avez pas besoin de les utiliser pour une intégration simple. Si vous souhaitez les utiliser pour d'autres raisons, vous pouvez consulter leur signification dans la documentation de l'API.

Ainsi, si notre intégration recevait cette réponse spécifique, nous souhaiterions rediriger cet utilisateur vers la salle d'attente : https://wait.crowdhandler.com/queen-victoria-hall.

Vous voyez autre chose ?

Il se peut que vous n'obteniez pas la réponse type ci-dessus. Si votre réponse diffère considérablement, l'un des problèmes suivants a pu se produire, en fonction de ce que vous constatez :

  • Une erreur ? Cela signifierait qu'il y a un problème avec les paramètres de votre requête. Le message d'erreur devrait vous indiquer où se situe le problème.
  • Pas d'informations sur la salle d'attente ? Si vous envoyez des URL qui n'entrent dans le champ d'application d'aucune de vos salles d'attente, vous recevrez un jeton et la valeur de « promoted » sera égale à 1, mais vous n'obtiendrez pas d'informations sur la salle d'attente en retour. Vous pouvez essayer de configurer une salle d'attente « fourre-tout » pour faciliter vos tests.
  • Pas de jeton ? Si vous essayez de tester l'appel en utilisant des URL correspondant à des noms de domaine qui ne sont même pas enregistrés sur votre compte CrowdHandler, vous obtiendrez tout de même la valeur 1 (nous ne sommes pas responsables de la protection de ce domaine ; donc, en ce qui nous concerne, tout va bien !). Mais vous ne recevrez pas de jeton.
  • Si vous obtenez le statut 3, cela signifie que votre adresse IP a été bloquée. Cela peut se produire lorsque vous effectuez un grand nombre de requêtes vers l'API publique à partir de la même adresse IP, ce qui est fréquent lors du test d'une intégration. Connectez-vous au panneau d'administration, repérez votre adresse IP (dans la rubrique « Domaines » → « Adresses IP ») et modifiez le statut de votre adresse IP pour qu'elle soit ignorée.

Bon, nous avons donc effectué notre premier appel, nous savons quel est le résultat et comment nous devons y réagir. Nous aborderons les détails concernant la gestion de ces informations après avoir traité le prochain appel.

3. Votre deuxième appel

GET /requests/:token

Dans le premier exemple, nous n'avions pas de jeton utilisateur. L'appel POST ne reçoit pas de jeton, il vous en renvoie un. C'est donc l'appel à effectuer lorsque l'utilisateur de votre site ne dispose pas de jeton. Mais si l'utilisateur est arrivé sur votre site après avoir été dans la salle d'attente et avoir été autorisé à passer, il disposera alors d' un jeton. Dans ce cas, vous devez vous assurer de l'utiliser et de le conserver pour vérifier son identité. En effet, si vous lui en attribuez un nouveau, il se retrouvera très probablement à nouveau dans la file d'attente.

Où puis-je trouver le jeton ?

Lorsque CrowdHandler redirige les utilisateurs vers votre site, il ajoute le jeton à l'URL. Celui-ci est intégré sous la forme d'un paramètre de chaîne de requête appelé « ch-id ». Par exemple : https://yoursite.com/your-url?ch-id=tok_S0mET0k3n. Vous devez donc vérifier si ce paramètre d'URL contient un jeton. Et si vous le trouvez, vous effectuez une requête GET au lieu d'une requête POST.

Mais ce n'est pas tout !

Votre utilisateur cliquera ensuite sur de nombreux autres liens de votre site web. Ainsi, pour vous assurer qu’il ne se retrouve pas à nouveau dans la « salle d’attente » , vous devez définir un cookie de session chaque fois que vous recevez le jeton en retour, et vérifier ce cookie chaque fois que vous ne trouvez pas « ch-id » dans l’URL. Si vous ne le trouvez toujours pas, envoyez la requête POST.

Les jetons ont-ils une date d'expiration ?

C'est vrai. Mais chaque fois que vous transmettez un jeton non valide, CrowdHandler ignorera ce jeton, traitera la requête comme si aucun jeton n'avait été défini, et vous renverra un nouveau jeton tout en traitant votre requête. Cela signifie que les jetons s'effacent d'eux-mêmes et que vous n'avez pas à vous soucier de leur suivi ni de leur expiration. Mais cela signifie également que le jeton que vous recevez en retour n'est pas nécessairement celui que vous avez envoyé. Vous devez faire confiance au jeton que vous recevez plutôt qu'à celui que vous avez envoyé ; veillez donc à définir le cookie à chaque fois.

Dois-je vérifier d'abord le cookie ou le paramètre de l'URL ?

Le paramètre URL. Dans certaines situations complexes, il est possible qu'un utilisateur dispose d'un nouveau jeton dans la salle d'attente, mais qu'un ancien cookie soit toujours stocké sur votre site. Si l'utilisateur provient de la salle d'attente, le nouveau jeton figurera dans l'URL ; vous devez alors privilégier ce jeton plutôt que celui, potentiellement obsolète, que vous aviez précédemment défini sous forme de cookie.

Bien sûr, l'absence du paramètre « ch-id » ne doit pas être interprétée comme une instruction visant à supprimer tout cookie existant. Vérifiez donc attentivement.

Et puis… l'appel :

La charge utile est la même que pour la requête POST, mais comme il s'agit ici d'une requête GET, nous envoyons les paramètres sous forme de paramètres GET, et non sous forme de JSON brut. L'URL a changé. Cette fois-ci, le jeton fait partie intégrante de l'URL.

La réponse ressemble beaucoup à la requête POST. À la différence près que, cette fois-ci, on constate que le jeton reçu est bien celui que nous avons envoyé. Les décisions que notre intégration doit prendre, sur la base de ces données, sont exactement les mêmes que pour la requête POST.

En conclusion

Les requêtes POST et GET renvoient les mêmes informations. Vous effectuez la requête POST lorsque vous n'avez pas encore reçu de jeton de la part de l'utilisateur, et la requête GET lorsque vous l'avez reçu. Ces requêtes ne s'enchaînent pas ; il s'agit de deux options alternatives. Dans les deux cas, la réponse se présentera sous le même format et l'action que vous effectuerez sera la même.

Vous devez enregistrer le jeton dans un cookie ou dans votre objet de session afin de pouvoir valider l'identité de l'utilisateur à chaque fois qu'il accède à différentes URL de votre site.

Faites attention lorsque vous configurez votre cookie de jeton ou votre session, car un utilisateur en attente pourrait essayer d'accéder à d'autres URL de votre site et vous ne voulez pas qu'il se retrouve à la fin de la file d'attente. C'est pourquoi :

  1. Nous vous recommandons de stocker le jeton dès que possible, sans attendre de savoir si cet utilisateur doit patienter ou non.
  2. Faites attention à la durée de validité des sessions. Votre application dispose peut-être d'un système de stockage des sessions avec un délai d'expiration de 20 minutes, mais l'utilisateur pourrait rester dans la salle d'attente pendant des heures. Un cookie de session qui n'expire que lorsque l'utilisateur ferme son navigateur est une bonne solution. Un cookie permanent pourrait même être préférable.

4. Quand passer votre premier appel

CrowdHandler a pour objectif de protéger votre site contre une charge excessive. Le but de cette validation est de s'assurer que l'utilisateur de votre site est bien censé accéder à cette URL à ce moment précis. Vous devez donc effectuer ces appels dès que possible dans le flux d'exécution de votre code. L'objectif principal est d'économiser du temps d'exécution et des ressources serveur. Dès que vous connaissez l'URL demandée et que vous êtes en mesure d'effectuer l'appel, vous devez le faire.

5. Que faire du résultat ?

  • Si la valeur de « promoted » est égale à 1, quittez le code de vérification et revenez au déroulement normal de votre application. Affichez l'URL comme vous le feriez habituellement.
  • Si la valeur de « promoted » est égale à 0, redirigez l'utilisateur vers la salle d'attente à l'aide du slug. Utilisez une redirection HTTP 302 si l'« utilisateur » est un bot légitime ; cela indique au bot que la redirection d'URL est temporaire.
  • Si vous recevez une réponse mal formée ou si l'appel à l'API échoue... CrowdHandler dispose de plusieurs niveaux de protection, mais il y a sont Il existe plusieurs raisons pour lesquelles cela pourrait se produire et auxquelles vous devez réagir. Il pourrait s'agir d'un problème réseau temporaire au sein de votre centre de données ou sur un réseau fédérateur Internet. Si l'appel à l'API échoue, ou si l'analyse d'un résultat valide échoue, ou encore si l'évaluation du promu Si la valeur est incorrecte, vous devez considérer cela comme une exception et la gérer. La manière dont vous la gérez dépend de vous :
    • La redirection en cas d'échec part du principe que, à défaut d'indication contraire, l'utilisateur doit être mis en file d'attente. Si vous connaissez le slug de votre salle d'attente standard (vous disposez peut-être d'une page par défaut avec un slug fixe), vous pouvez y rediriger l'utilisateur. Si vous ne le connaissez pas, vous pouvez rediriger l'utilisateur vers https://wait.crowdhandler.com, où il aura accès à un modèle générique, vérifiera régulièrement si de nouvelles informations sont disponibles et sera redirigé vers votre site ou vers la salle d’attente appropriée lorsque le service reprendra normalement.
    • Confiance en cas d'échec: vous pouvez choisir d'autoriser l'utilisateur à accéder à la page si l'appel à l'API échoue. Ce choix dépendra de la fréquence à laquelle votre site enregistre un trafic élevé et du degré de prévisibilité de ces pics de trafic. Si vous avez installé CrowdHandler uniquement pour une utilisation occasionnelle et planifiée, avec des salles d'attente spécifiques à certains événements, vous préférerez peut-être faire confiance aux utilisateurs dans le cas où vous ne recevriez pas de réponses correctement formées de la part de l'API CrowdHandler.

6. Rediriger un utilisateur

Lorsque vous redirigez un utilisateur, vous devez inclure les paramètres encodés suivants dans l'URL de redirection.

  1. ch-id: le jeton renvoyé par l'API.
  2. url: l'URL demandée par l'utilisateur. Si les paramètres de la chaîne de requête sont importants pour vous (que ce soit à des fins de marketing ou de suivi, ou parce que vous les utilisez pour des identifiants de produits ou autres), vous devez vous assurer qu'ils sont également transmis dans le paramètre « url ».
  3. ch-public-key : si vous ne connaissez pas le slug de la salle d'attente de vos utilisateurs, peut-être parce que vous avez reçu une réponse mal formée ou aucune réponse, vous pouvez alors envoyer votre clé publique à la place du slug, en utilisant ce paramètre. Cela permettra à la salle d'attente de secours de CrowdHandler d'utiliser votre clé pour rechercher le slug correct et de gérer la situation de manière appropriée.

7. Le dernier appel. Suivi des performances des pages

PUT /responses/:id

L'enregistrement des performances de votre page permet à CrowdHandler de surveiller les performances de votre domaine. Cela s'avère utile pour surveiller les pics de trafic et est indispensable pour activer la fonctionnalité d'optimisation automatique.

Cet appel est un PUT. Il est destiné à une nouvelle ressource /responses/:id. L'identifiant vous a été fourni sous le nom de responseID dans le résultat du premier appel que vous avez effectué.

La charge utile de cet appel se présente à peu près comme suit :

{
    "code": 200,
    "time": 2000
}
  • Le code correspond à la réponse HTTP de la page que vous servez à l'utilisateur. Il s'agit généralement d'un 200, mais si vous êtes en mesure de détecter les codes d'erreur HTTP, vous devez les transmettre. Cela permettra à CrowdHandler d'identifier les moments où votre site web rencontre des difficultés*, afin que la fonction d'ajustement automatique puisse intervenir. Si vous omettez ce paramètre, CrowdHandler utilisera par défaut la valeur 200.
  • temps Il s'agit du temps de chargement de votre page en millisecondes. Vous pouvez le calculer comme suit :

    • prendre le temps dès la réception de votre demande (a)

    • prendre le temps, juste avant d'envoyer cette requête PUT (b)

    • en soustrayant b de a et en s'assurant que la différence de temps est exprimée en millisecondes (millièmes de seconde).

      Même si cela semble assez simple, vous devez faire preuve d’une grande prudence. Les différents langages et frameworks disposent de méthodes variées pour mesurer le temps par petits incréments ; il peut y avoir des différences, voire des problèmes de performances, selon que vous utilisiez des machines virtuelles ou des serveurs physiques, ainsi qu’en fonction des types de processeurs. Certains frameworks proposent des API spécialement conçues pour suivre les performances des pages. Si vous vous sentez à l’aise, vous pouvez fournir une mesure très précise à CrowdHandler. Si vous n’êtes pas sûr de vous, omettez simplement ce paramètre. Dans ce cas, CrowdHandler effectuera son propre calcul en se basant sur le délai entre la requête initiale et la requête PUT suivante. L'estimation du temps de chargement de la page peut être légèrement affectée par les temps de réseau et présente une résolution inférieure, mais ces informations sont suffisantes pour un contrôle d'intégrité et constituent une meilleure alternative que la valeur extrêmement imprécise qui pourrait être fournie si votre calcul était erroné.

* Une réponse accompagnée d'un code d'erreur est traitée par CrowdHandler de la même manière qu'une requête dépassant votre temps de réponse maximal. Ainsi, si vous renvoyez des erreurs 500 à un rythme très rapide, mais que le nombre d'erreurs dépasse le seuil en pourcentage que vous jugez acceptable, la fonction d'ajustement automatique ralentira le trafic comme si ces requêtes dépassaient le seuil acceptable de temps de chargement des pages.

Quand passer cet appel.

Bien que l'appel initial doive être effectué le plus tôt possible, cet appel doit être effectué le plus tard possible, après avoir affiché la page à l'utilisateur. De plus — cela peut sembler évident, mais vous ne devez effectuer cet appel que si vous avez effectivement affiché l'URL. Si vous avez redirigé l'utilisateur vers la « salle d'attente », vous devez ignorer complètement cet appel. Ainsi, après votre premier appel, il existe une branche conditionnelle entre l'envoi de la redirection ou l'affichage de la page, et l'enregistrement des performances.

8. Mettre tout cela en pratique

Le pseudo-code** ci-dessous rassemble tous ces éléments pour décrire une intégration simple, mais complète. Vous verrez qu'il permet de comprendre le concept plus rapidement que les longues explications que nous avons données jusqu'à présent, mais vous devriez néanmoins vous reporter aux notes pour avoir le contexte.

chKey = <your public key>
timeA = Timer.getTimeInMs()
request = Controller.getRequest()
response = Controller.startRresponse()
trustOnFail = true

if request.urlParams["ch-id"]
    # token in query string. We want to set cookie so we recognise this user
    response.cookies["ch-id"] = request.urlParams["ch-id"]
    # and we'll strip ch-id param and redirect to discourage token sharing
    cleanParams = request.urlParams.unset("ch-id")
    response.redirect(request.url, cleanParams, 302)
    response.end
else
    # set up the API gateway
    crowdhandler = HttpAPI.create(baseURL="https://api.crowdhandler.com/v1/", authentication=chKey)
    params = {"url": request.url, "ip": request.host, "agent": request.userAgent, "lang": request.acceptLang}
    # look for crowdhandler token in the cookie
    token = request.cookies["ch-id"]

    # check this user's request
    try
        if token
            # user has token
            result = crowdhandler.get("requests/"+token, params)
        else
            # user needs new token
            result = crowdhandler.post("requests/", params)
        end
    catch
        # api call failed!
        if trustOnFail
            # we do nothing
            break
        else
            # we send user to waiting room
            queryParams = {"url": request.url, "ch-id": token, "ch-public-key": chKey}
            response.redirect("https://wait.crowdhandler.com?", queryParams, 302)
            response.end
        end
end

# if we got here, we have a valid response.
# It's possible that the API has responded with a new token.
token = response.token
response.cookies["ch-id"] = token

if result.promoted
    # this token is good for this url
    # render your page / hand back control / you do you
    response.html = "Your Content"
    response.end
    # all done? Now to log the performance
    time = timeA - Timer.getTimeinMs()
    crowdhandler.put("/responses/"+result.responseID, {"code": 200, "time": time})
else
    # the user with this token needs to wait
   response.redirect("https://wait.crowdhandler.com"+result.slug+"?", {"url": request.url, "ch-id": token}, 302)
end

** C'est le fruit d'un croisement entre Ruby et Python, deux langages faciles à lire, doté d'API imaginaires et simples permettant d'effectuer des appels API, de récupérer des données de requête et d'envoyer des réponses. Nous espérons que vous n'aurez aucun mal à lire entre les lignes.

Découvrez notre SDK PHP pour accéder à une bibliothèque de code entièrement fonctionnelle.