Schritt-für-Schritt-Anleitung zur Integration einer einfachen serverseitigen API

In dieser Anleitung wird erläutert, wie eine grundlegende serverseitige API-Integration realisiert wird.

Dadurch wird überprüft, ob der Nutzer auf Ihrer Website berechtigt ist, auf die aktuelle URL zuzugreifen, und andernfalls wird er in einen Warteraum weitergeleitet.

Dieser Leitfaden richtet sich an Entwickler. Er setzt Kenntnisse über APIs usw. voraus.

Diese Integration nutzt die öffentlichen Ressourcen der CrowdHandler-API unter Verwendung des öffentlichen Schlüssels. Sie ist für alle Tarife verfügbar, einschließlich der kostenlosen Stufe.

1. Verbindung zur API herstellen

Zunächst benötigen Sie Ihren öffentlichen Schlüssel. Lesen Sie unsere Einführung in die API, um Zugriff auf Ihren API-Schlüssel zu erhalten.

2. Der erste Anruf

POST /requests/

Wir verwenden hier Postman, um die Aufrufe zu veranschaulichen. Es ist eine hervorragende Möglichkeit, API-Aufrufe durchzuführen, das Senden von Parametern zu testen und zu verstehen, welche Antworten zurückkommen, während Sie Ihre Integration zusammenstellen.

Wir verwenden „Basic Auth“, um unseren Schlüssel zu übermitteln. In Postman können wir diesen einmalig auf der Registerkarte „Autorisierung“ eingeben und für alle von uns durchgeführten Aufrufe speichern. Der Schlüssel wird in das Feld „Benutzername“ eingegeben. Das Passwort wird ignoriert.

Nachdem wir nun unseren Authentifizierungs-Header eingerichtet haben, beginnen wir mit einem POST-Aufruf an https://api.crowdhandler.com/v1/requests. Dieser Aufruf dient dazu, eine neue Anfrage an eine URL auf Ihrer Website zu initiieren, um zu prüfen, ob dieser Benutzer Zugriff erhalten oder weitergeleitet werden soll.

Der POST-Aufruf erwartet die folgende JSON-Nutzlast:

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

Gehen wir diese Parameter einmal durch:

  • url – Dies ist die URL, auf die Ihr Benutzer zugreifen möchte. Woher Sie diese beziehen, hängt von Ihrer Anwendung, Ihrer Programmiersprache und Ihrem Framework ab. Es kann sich um eine CGI-Variable handeln, oder Sie verfügen möglicherweise über eine Art Front-Controller/Router. Die URL muss vollständig sein, einschließlich des Protokolls. CrowdHandler unterstützt ausschließlich HTTPS.
  • ip – Dies ist die IP-Adresse der Anfrage des Benutzers. Auch hier hängt es von Ihrer Programmiersprache und Ihrem Framework ab, woher Sie diese Information beziehen. Die Angabe der IP-Adresse ist erforderlich. Sie dient der Betrugsprävention und der Erkennung von Bots.
  • agent – Dies ist die User-Agent-Zeichenkette. Auch diese Angabe ist erforderlich. Sie sollten sie aus dem HTTP-Header „User-Agent“ abrufen.
  • lang – Dies ist die bevorzugte Sprache des Benutzers. Es handelt sich um einen optionalen Parameter, der bei der Identifizierung betrügerischer Agenten helfen kann. Sie können ihn aus dem HTTP-Header „Accept-Language“ abrufen.

Wenn alles in Ordnung ist und die von Ihnen angegebene URL durch einen Warteraum geschützt ist, sollten Sie eine Antwort erhalten, die in etwa so aussieht:

{
    "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
    }
}

Die Ausgabe durchgehen:

  • Token: Das Token ist die Kennung des Benutzers. Da wir zunächst kein Token hatten, haben wir eine POST-Anfrage gestellt, für die kein Token erforderlich ist. Das bedeutet, dass wir bei unserem ersten Aufruf ein neues Token erhalten haben.
  • „promoted“ ist das Hauptattribut, das für uns von Interesse ist. Ein Wert von 0 bedeutet, dass sich der Benutzer mit diesem Token für die angegebene URL in die Warteschlange einreihen muss. Ein Wert von 1 bedeutet, dass der Benutzer sich nicht in die Warteschlange einreihen muss. Dieses Token hat den Wert „promoted“ 0, was darauf hinweist, dass sich dieser Benutzer in die Warteschlange einreihen muss.
  • slug: „slug“ gibt die Adresse des Warteraums an. Die vollständige Adresse des Warteraums lautet https://wait.crowdhandler.com/your-slug
  • „responseID“ ist eine eindeutige Kennung, die die soeben erhaltene Antwort identifiziert. Wir verwenden diese möglicherweise später, um die Leistung dieser Anfrage über die CrowdHandler-API zu protokollieren.
  • Die anderen Attribute sind interessant und können bei der Fehlerbehebung und beim Debugging hilfreich sein, aber für eine einfache Integration müssen Sie keines davon verwenden. Wenn Sie sie aus anderen Gründen nutzen möchten, können Sie ihre Bedeutung in der API-Dokumentation nachschlagen.

Wenn unsere Integration also genau diese Antwort erhalten hätte, würden wir diesen Nutzer in den Warteraum umleiten wollen: https://wait.crowdhandler.com/queen-victoria-hall.

Siehst du etwas anderes?

Möglicherweise erhalten Sie nicht die oben angegebene Beispielantwort. Wenn Ihre Antwort deutlich davon abweicht, könnte je nach dem, was Sie sehen, einer der folgenden Fehler vorliegen:

  • Ein Fehler? Das würde darauf hindeuten, dass mit Ihren Anfrageparametern etwas nicht stimmt. Der Fehler sollte Ihnen Aufschluss darüber geben, was Sie falsch machen.
  • Keine Informationen zum Warteraum? Wenn Sie URLs senden, die nicht in den Geltungsbereich eines Ihrer Warteräume fallen, erhalten Sie ein Token, und „promoted“ hat den Wert 1, aber Sie erhalten keine Informationen zum Warteraum zurück. Sie könnten versuchen, einen „Catch-All“-Warteraum einzurichten, um Ihre Tests zu erleichtern.
  • Kein Token? Wenn Sie versuchen, den Aufruf mit URLs zu testen, die auf Domainnamen verweisen, die nicht einmal in Ihrem CrowdHandler-Konto registriert sind, erhalten Sie dennoch den Wert 1 als Rückgabewert (wir sind nicht für den Schutz dieser Domain verantwortlich, daher steht es aus unserer Sicht auf „Grün“!). Sie erhalten jedoch kein Token.
  • Wenn Sie den Status 3 erhalten, bedeutet dies, dass Ihre IP-Adresse gesperrt wurde. Dies kann passieren, wenn Sie zahlreiche öffentliche API-Anfragen von derselben IP-Adresse aus stellen, was beim Testen einer Integration häufig vorkommt. Melden Sie sich im Admin-Bereich an, suchen Sie Ihre IP-Adresse (unter „Domains“ → „IPs“) und ändern Sie den Status Ihrer IP-Adresse auf „Ignorieren“.

Okay, wir haben also unseren ersten Aufruf durchgeführt, wissen, was die Ausgabe ist und wie wir darauf reagieren sollen. Wir werden die Einzelheiten zum Umgang mit diesen Informationen besprechen, nachdem wir den nächsten Aufruf behandelt haben.

3. Ihr zweiter Anruf

GET /requests/:token

Im ersten Beispiel hatten wir kein Benutzer-Token. Der POST-Aufruf empfängt kein Token, sondern gibt eines zurück. Das ist also der Aufruf, den Sie verwenden sollten, wenn der Benutzer auf Ihrer Website kein Token hat. Wenn der Benutzer jedoch auf Ihrer Website gelandet ist, weil er sich im Warteraum befand und es geschafft hat, dann verfügt er über ein Token. In diesem Fall sollten Sie sicherstellen, dass Sie dieses Token verwenden und speichern, um den Benutzer zu überprüfen. Denn wenn Sie ihm ein neues Token zuweisen, landet er höchstwahrscheinlich wieder in der Warteschlange.

Wo finde ich das Token?

Wenn CrowdHandler Nutzer auf Ihre Website weiterleitet, fügt es das Token an die URL an. Es wird als Parameter der Abfragezeichenfolge mit dem Namen „ch-id“ hinzugefügt. Beispiel: https://yoursite.com/your-url?ch-id=tok_S0mET0k3n. Sie müssen also diesen URL-Parameter auf das Vorhandensein eines Tokens überprüfen. Wenn Sie dort ein Token finden, führen Sie den GET-Aufruf anstelle des POST-Aufrufs durch.

Aber das ist noch nicht alles!

Ihr Nutzer wird anschließend auf zahlreiche weitere Links auf Ihrer Website klicken. Um sicherzustellen, dass der Nutzer nicht wieder im Wartezimmer landet, müssen Sie jedes Mal, wenn Sie das Token zurückerhalten, ein Session-Cookie setzen und das Cookie überprüfen , wenn Sie „ch-id“ nicht in der URL finden können. Wenn Sie es immer noch nicht finden, senden Sie die POST-Anfrage.

Verfallen die Token?

Das tun sie. Aber wann immer Sie ein ungültiges Token übermitteln, ignoriert CrowdHandler dieses Token, behandelt die Anfrage so, als wäre kein Token gesetzt worden, und sendet Ihnen ein neues Token zurück, während Ihre Anfrage geprüft wird. Das bedeutet, dass sich die Token von selbst bereinigen und Sie sich keine Gedanken über die Nachverfolgung und den Ablauf von Token machen müssen. Es bedeutet aber auch, dass das Token, das Sie zurückerhalten, nicht unbedingt dasjenige ist, das Sie gesendet haben. Sie müssen dem empfangenen Token mehr vertrauen als dem von Ihnen gesendeten; setzen Sie das Cookie daher jedes Mal.

Sollte ich zuerst das Cookie oder den URL-Parameter überprüfen?

Der URL-Parameter. In komplexen Situationen kann es vorkommen, dass Ihr Nutzer im Warteraum zwar ein neues Token hat, auf Ihrer Website jedoch noch ein altes Cookie gespeichert ist. Wenn der Nutzer aus dem Warteraum weitergeleitet wird, ist das neue Token in der URL enthalten. Sie sollten diesem Token den Vorzug vor dem möglicherweise veralteten Token geben, das Sie zuvor als Cookie gesetzt haben.

Natürlich sollten Sie das Fehlen des Parameters „ch-id“ nicht als Anweisung zum Löschen eines bereits vorhandenen Cookies verstehen. Prüfen Sie dies daher sorgfältig.

Also dann … der Anruf:

Die Nutzlast ist dieselbe wie bei der POST-Anfrage, doch da es sich hierbei um eine GET-Anfrage handelt, senden wir die Parameter als GET-Parameter und nicht als rohes JSON. Die URL hat sich geändert. Diesmal ist das Token Teil der URL.

Die Antwort sieht der POST-Anfrage sehr ähnlich. Der Unterschied besteht darin, dass wir diesmal sehen können, dass das empfangene Token mit dem von uns gesendeten übereinstimmt. Die Entscheidungen, die unsere Integration auf der Grundlage dieser Daten treffen muss, sind genau dieselben wie bei der POST-Anfrage.

Zusammenfassend lässt sich sagen

Der POST-Aufruf und der GET-Aufruf liefern dieselben Informationen. Den POST-Aufruf führen Sie aus, wenn Sie noch kein Token vom Benutzer erhalten haben, und den GET-Aufruf, wenn Sie bereits ein Token erhalten haben. Diese Aufrufe erfolgen nicht nacheinander, sondern stellen Alternativen dar. In beiden Fällen hat die Antwort dasselbe Format, und die von Ihnen durchgeführte Aktion ist dieselbe.

Sie müssen das Token in einem Cookie oder in Ihrem Session-Objekt speichern, damit Sie den Benutzer bei jedem Zugriff auf verschiedene URLs Ihrer Website wiederholt authentifizieren können.

Seien Sie vorsichtig beim Setzen Ihres Token-Cookies oder Ihrer Session, denn ein wartender Nutzer könnte versuchen, andere URLs auf Ihrer Website aufzurufen, und Sie möchten nicht, dass er dadurch wieder ganz ans Ende der Warteschlange rutscht. Aus diesem Grund:

  1. Wir empfehlen, das Token so bald wie möglich zu speichern und nicht abzuwarten, bis feststeht, ob dieser Benutzer warten soll oder nicht.
  2. Achten Sie auf das Ablaufen der Sitzung. Ihre Anwendung verfügt möglicherweise über einen Sitzungsspeicher mit einer Zeitüberschreitung von 20 Minuten, doch der Benutzer könnte sich stundenlang im Warteraum aufhalten. Ein Sitzungs-Cookie, das erst abläuft, wenn der Benutzer seinen Browser schließt, ist eine gute Wahl. Ein permanentes Cookie ist möglicherweise sogar noch besser.

4. Wann Sie Ihren ersten Anruf tätigen sollten

Der Zweck von CrowdHandler besteht darin, Ihre Website vor übermäßiger Auslastung zu schützen. Der Zweck der Validierungsprüfung besteht darin, sicherzustellen, dass der Benutzer auf Ihrer Website zu diesem Zeitpunkt tatsächlich auf diese URL zugreifen sollte. Daher sollten Sie diese Aufrufe so früh wie möglich im Ablauf Ihres Codes durchführen. Das übergeordnete Ziel besteht darin, Serverausführungszeit und Ressourcen zu sparen. Sobald Sie die URL-Anfrage kennen und den Aufruf durchführen können, sollten Sie dies tun.

5. Was mit dem Ergebnis geschehen soll

  • Wenn „promoted“ den Wert 1 hat, dann verlassen Sie den Prüfcode und kehren Sie zu Ihrem normalen Anwendungsablauf zurück. Stellen Sie die URL wie gewohnt bereit.
  • Wenn „promoted“ den Wert 0 hat, leite den Benutzer mithilfe des Slugs in den Warteraum weiter. Verwende eine 302-HTTP-Weiterleitung, falls es sich bei dem „Benutzer“ um einen legitimen Bot handelt; dadurch wird dem Bot mitgeteilt, dass die URL-Weiterleitung nur vorübergehend ist.
  • Falls Sie eine fehlerhafte Antwort erhalten oder der API-Aufruf fehlschlägt... CrowdHandler verfügt über zahlreiche Schutzebenen, aber es gibt sind Gründe, warum dies passieren könnte und Sie darauf reagieren müssen. Möglicherweise liegt ein vorübergehendes Netzwerkproblem in Ihrem Rechenzentrum oder im Internet-Backbone vor. Wenn der API-Aufruf fehlschlägt, das Parsen eines gültigen Ergebnisses fehlschlägt oder die Auswertung des befördert Wenn der Wert fehlschlägt, müssen Sie dies als Ausnahme behandeln und entsprechend reagieren. Wie Sie dabei vorgehen, bleibt Ihnen überlassen:
    • „Redirect on fail“ geht davon aus, dass der Benutzer in die Warteschlange gestellt werden sollte, sofern Sie nichts Besseres wissen. Wenn Sie den Slug Ihres Standard-Warteraums kennen (möglicherweise verfügen Sie über einen Standard-Warteraum mit einem festen Slug), können Sie den Benutzer dorthin weiterleiten. Falls Sie ihn nicht kennen, können Sie den Benutzer an folgende Adresse weiterleiten: https://wait.crowdhandler.com, wo dem Nutzer eine generische Vorlage angezeigt wird, regelmäßig nach besseren Informationen abgefragt wird und er zu Ihrer Website oder zum entsprechenden Warteraum weitergeleitet wird, sobald der normale Betrieb wieder aufgenommen wird.
    • „Trust on fail“ – Sie können festlegen, dass der Nutzer Zugriff auf die Seite erhält, wenn der API-Aufruf fehlschlägt. Dies hängt davon ab, wie häufig auf Ihrer Website hoher Datenverkehr auftritt und wie vorhersehbar die Muster sind. Wenn Sie CrowdHandler nur für den gelegentlichen, geplanten Einsatz mit ereignisspezifischen Warteräumen installiert haben, ziehen Sie es möglicherweise vor, den Nutzern zu vertrauen, falls Sie keine wohlgeformten Antworten von der CrowdHandler-API erhalten.

6. Umleitung eines Benutzers

Wenn Sie einen Benutzer weiterleiten, sollten Sie die folgenden URL-kodierten Parameter in der Weiterleitungs-URL angeben.

  1. ch-id: Das von der API zurückgegebene Token.
  2. url: Die URL, die der Benutzer angefordert hat. Wenn Ihnen die Parameter der Abfragezeichenfolge wichtig sind (sei es aus Marketing- oder Tracking-Gründen oder weil Sie sie für Produkt-IDs und Ähnliches verwenden), müssen Sie sicherstellen, dass diese ebenfalls als Teil des URL-Parameters übergeben werden.
  3. ch-public-key: Wenn Sie den Slug des Warteraums für Ihre Benutzer nicht kennen – beispielsweise, weil Sie eine fehlerhafte Antwort oder gar keine Antwort erhalten haben –, können Sie mithilfe dieses Parameters anstelle des Slugs Ihren öffentlichen Schlüssel senden. Auf diese Weise kann der Safety-Net-Warteraum von CrowdHandler anhand Ihres Schlüssels den richtigen Slug ermitteln und entsprechend weiterverarbeiten.

7. Der letzte Aufruf. Erfassung der Seitenleistung

PUT /responses/:id

Durch die Protokollierung der Leistung Ihrer Seite kann CrowdHandler die Leistung Ihrer Domain überwachen. Dies ist bei der Überwachung von hohem Datenverkehr hilfreich und für die Aktivierung der Autotune-Funktion unerlässlich.

Dieser Aufruf ist ein PUT-Aufruf. Er wird an eine neue Ressource /responses/:id gesendet. Die ID wurde Ihnen als „responseID“ im Ergebnis Ihres ersten Aufrufs mitgeteilt.

Die Nutzdaten für diesen Aufruf sehen in etwa so aus:

{
    "code": 200,
    "time": 2000
}
  • Der Code ist die HTTP-Antwort für die Seite, die Sie dem Nutzer bereitstellen. Normalerweise lautet er 200, aber wenn Sie HTTP-Fehlercodes abfangen können, sollten Sie diese übermitteln. Dies hilft CrowdHandler dabei, zu erkennen, wann Ihre Website Probleme hat*, sodass die automatische Optimierung Maßnahmen ergreifen kann. Wenn Sie diesen Parameter weglassen, verwendet CrowdHandler standardmäßig den Wert 200.
  • Zeit ist die Ladezeit Ihrer Seite in Millisekunden. Sie können diese wie folgt berechnen:

    • sich gleich nach Erhalt Ihrer Anfrage die Zeit nehmen (a)

    • Nimm dir kurz vor dem Absenden dieses PUT (b) etwas Zeit

    • a um b subtrahieren und sicherstellen, dass die Zeitdifferenz in Millisekunden (Tausendstelsekunden) angegeben wird.

      Das klingt zwar recht einfach, erfordert jedoch einiges an Sorgfalt. Verschiedene Sprachen und Frameworks verfügen über unterschiedliche Methoden zur Erfassung von Zeit in kleinen Schritten; je nachdem, ob Sie virtuelle Maschinen oder Bare-Metal-Server sowie unterschiedliche Prozessortypen verwenden, kann es zu Abweichungen oder Leistungsproblemen kommen. Einige Frameworks bieten spezielle APIs zur Erfassung der Seitenleistung. Wenn Sie sich sicher sind, können Sie CrowdHandler einen sehr genauen Wert übermitteln. Wenn Sie sich weniger sicher sind, lassen Sie diesen Parameter einfach weg. In diesem Fall führt CrowdHandler seine eigene Berechnung auf Basis der Zeit zwischen der ersten Anfrage und dem nachfolgenden PUT-Aufruf durch. Die Schätzung der Seitenladezeit kann zwar durch Netzwerkzeiten etwas beeinflusst werden und weist eine geringere Genauigkeit auf, doch die Informationen reichen für einen Zustandscheck aus und sind besser als der extrem ungenaue Wert, der bei einer fehlerhaften Berechnung übermittelt werden könnte.

* Eine Antwort mit einem Fehlercode wird von CrowdHandler genauso behandelt wie eine Anfrage, die Ihre maximale Antwortzeit überschreitet. Wenn Sie also sehr schnell 500-Fehler ausgeben, die Anzahl der Fehler jedoch Ihren zulässigen prozentualen Schwellenwert überschreitet, drosselt Autotune den Datenverkehr so, als ob diese Anfragen die zulässige Schwelle für die Seitenladezeit überschreiten würden.

Wann man den Anruf tätigen sollte.

Der erste Aufruf sollte zwar so früh wie möglich erfolgen, dieser Aufruf hier jedoch so spät wie möglich, nämlich erst nachdem Sie die Seite dem Nutzer bereitgestellt haben. Außerdem – es klingt zwar selbstverständlich, aber Sie führen diesen Aufruf nur aus, wenn Sie die URL tatsächlich bereitgestellt haben. Wenn Sie den Nutzer in den Warteraum weitergeleitet haben, sollten Sie diesen Aufruf komplett überspringen. Nach Ihrem ersten Aufruf gibt es also eine bedingte Verzweigung zwischen dem Senden der Weiterleitung bzw. dem Bereitstellen der Seite und der Protokollierung der Leistung.

8. Alles zusammenführen

Der folgende Pseudocode** fasst alles zusammen und beschreibt eine einfache, aber vollständige Integration. Sie werden feststellen, dass er das Prinzip schneller verdeutlicht als die ausführlichen Erklärungen, die wir bisher gegeben haben; dennoch sollten Sie die Anmerkungen zur Einordnung heranziehen.

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

** Es ist das Mischlings-Kind von Ruby und Python, zwei gut lesbaren Sprachen, mit fiktiven und einfachen APIs zum Ausführen von API-Aufrufen, zum Abrufen von Anfragedaten und zum Senden von Antworten. Wir hoffen, dass Sie leicht zwischen den Zeilen lesen können.

Werfen Sie einen Blick auf unser PHP-SDK, um eine voll funktionsfähige Code-Bibliothek zu erhalten.