Guía paso a paso para una integración básica de una API del lado del servidor

This guide explains how to achieve a basic server-side API integration.

Esto verificará que el usuario de tu página web tenga permiso para acceder a la URL actual y, en caso contrario, lo redirigirá a una sala de espera.

Esta guía está dirigida a desarrolladores. Se da por hecho que el lector está familiarizado con las API, etc.

Esta integración utiliza los recursos públicos de la API de CrowdHandler, mediante la clave pública. Está disponible para cualquier plan, incluido el nivel gratuito.

1. Connecting to the API

First you will need your public key. Read our introduction to the API to get access to your API key.

2. Making your first call

POST /solicitudes/

Aquí estamos utilizando Postman para mostrar las llamadas. Es una forma estupenda de realizar llamadas a la API, probar el envío de parámetros y comprender qué resultados se obtienen mientras se va configurando la integración.

We're using Basic Auth to send our key. Postman will allow us to enter this once under the authorization tab, and save it for all the calls we're making. The key goes into the Username field. The Password is ignored.

Ahora que ya tenemos configurado nuestro encabezado de autenticación, vamos a empezar realizando una llamada POST a https://api.crowdhandler.com/v1/requests. Esta llamada se utiliza para iniciar una nueva solicitud a una URL de tu sitio web, con el fin de comprobar si este usuario debe obtener acceso o ser redirigido.

La llamada POST espera la siguiente carga útil JSON:

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

Repasemos estos parámetros:

  • url - This is the URL that your user is trying to access. Where you get this from depends upon your application, language and framework. It may be a CGI variable, or you may have some kind of front-controller/router. The URL needs to be complete, including protocol. CrowdHandler only supports HTTPS.
  • ip - Esta es la dirección IP de la solicitud del usuario. Una vez más, el lugar desde donde se obtenga esta información dependerá del lenguaje de programación y del marco de trabajo que utilices. La dirección IP es obligatoria. Se utiliza para la prevención del fraude y la detección de bots.
  • agent: esta es la cadena de agente de usuario. También es un campo obligatorio. Debes obtenerla del encabezado HTTP «User-Agent ».
  • lang - this is the user's preferred language. It is an optional parameter, and can assist with identifying fraudulent agents. You can get it from the HTTP header Accept-Language.

If all's well, and the URL you provided is protected by a waiting room, you should receive a response that looks something like this:

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

Repaso de los resultados:

  • El token es el identificador del usuario. Al principio no teníamos ninguno, así que realizamos una solicitud POST, que no lo requiere, y esto significa que recibimos un nuevo token con nuestra primera solicitud.
  • promoted is the main attribute that we are interested in. A value of 0 means that the user with this token needs to queue for the specified URL. A value of 1 means that the user does not need to queue. This token has promoted value 0 which indicates we need this user to queue.
  • slug the slug indicates the address of the waiting room. The full address of the waiting room will be https://wait.crowdhandler.com/your-slug
  • responseID es un identificador único que identifica la respuesta que acabas de recibir. Es posible que lo utilicemos más adelante para registrar el rendimiento de esta solicitud mediante la API de CrowdHandler.
  • Los demás atributos son interesantes y pueden resultar útiles para la resolución de problemas y la depuración, pero no es necesario utilizar ninguno de ellos para una integración sencilla. Si te interesa utilizarlos por otros motivos, puedes consultar su significado en la documentación de la API.

Así pues, si nuestra integración recibiera esta respuesta concreta, querríamos redirigir a este usuario a la sala de espera: https://wait.crowdhandler.com/queen-victoria-hall.

Seeing something else?

Es posible que no obtengas la respuesta de ejemplo que aparece arriba. Si tu respuesta es muy diferente, puede que haya surgido alguno de los siguientes problemas, dependiendo de lo que estés viendo:

  • ¿Un error? Esto indicaría que hay algún problema con los parámetros de tu solicitud. El mensaje de error debería indicarte cuál es el problema.
  • ¿No hay información sobre la sala de espera? Si envías URL que no entran dentro del ámbito de ninguna de tus salas de espera, recibirás un token y el valor de «promoted» será 1, pero no obtendrás información sobre la sala de espera. Podrías intentar configurar una sala de espera genérica para facilitar tus pruebas.
  • ¿No tienes token? Si intentas probar la llamada utilizando URL de nombres de dominio que ni siquiera están registrados en tu cuenta de CrowdHandler, seguirás recibiendo un 1 como valor promocionado (no nos hacemos responsables de proteger ese dominio, así que, por lo que a nosotros respecta, ¡puedes seguir adelante!). Pero no recibirás ningún token.
  • If you are receiving status 3, this means that your IP has been blocked. This can happen when you make lots of public API requests from the same IP, and is common when testing an integration. Log in to the admin panel, find your IP (under domains → IPs) and change the status on your IP to ignore.

Vale, pues ya hemos realizado nuestra primera llamada, sabemos cuál es el resultado y cómo debemos reaccionar ante él. Hablaremos de los detalles sobre cómo gestionar esta información una vez que hayamos visto la siguiente llamada.

3. Your second call

GET /solicitudes/:token

En el primer ejemplo no teníamos ningún token de usuario. La llamada POST no recibe un token, sino que te devuelve uno. Así que esa es la llamada que hay que realizar cuando el usuario de tu sitio web no tiene token. Pero si el usuario ha llegado a tu sitio web porque estaba en la sala de espera y ha conseguido pasar, entonces tendrá un token. En ese caso, debes asegurarte de utilizarlo y conservarlo para verificar su identidad. Porque si le das uno nuevo, lo más probable es que vuelva a acabar en la cola.

Where do I find the token?

When CrowdHandler redirects users to your site it appends the token to the url. It goes in as a query string parameter called ch-id. E.g. https://yoursite.com/your-url?ch-id=tok_S0mET0k3n. So you need to check that URL parameter for a token. And if you find it there, you make the GET call instead of the POST call.

But that's not all!

A continuación, el usuario hará clic en muchos otros enlaces de tu página web. Por lo tanto, para asegurarte de que el usuario no vuelva a la «sala de espera» , debes establecer una cookie de sesión cada vez que recibas el token, y comprobar la cookie cada vez que no encuentres «ch-id» en la URL. Si sigues sin encontrarla, envía la solicitud POST.

Do the tokens expire?

Así es. Pero cada vez que envíes un token no válido, CrowdHandler lo ignorará, tratará la solicitud como si no se hubiera establecido ningún token y te devolverá un nuevo token, además de procesar tu solicitud. Esto significa que los tokens se renuevan automáticamente y no tienes que preocuparte por su seguimiento ni por su caducidad. Pero también significa que el token que recibes no es necesariamente el que enviaste. Debes confiar en el token que recibes más que en el que enviaste, así que configura la cookie cada vez.

Should I check the cookie first or the URL parameter?

El parámetro de la URL. En situaciones complejas, es posible que el usuario tenga un nuevo token en la sala de espera, pero que aún conserve una cookie antigua almacenada en tu sitio web. Si el usuario procede de la sala de espera, el nuevo token aparecerá en la URL; debes dar prioridad a ese token frente al que pudieras haber establecido anteriormente como cookie y que podría estar desactualizado.

Por supuesto, no debes interpretar la ausencia del parámetro «ch-id» como una indicación para borrar cualquier cookie existente. Así que compruébalo con cuidado.

So then... the call:

La carga útil es la misma que en la solicitud POST, pero como se trata de una solicitud GET, enviamos los parámetros como parámetros GET, no como JSON sin formato. La URL ha cambiado. En esta ocasión, el token forma parte de la URL.

La respuesta es muy similar a la solicitud POST. La única diferencia es que, en esta ocasión, podemos ver que el token que hemos recibido es el mismo que enviamos. Las decisiones que debe tomar nuestra integración, basándose en estos datos, son exactamente las mismas que en el caso de la solicitud POST.

In Conclusion

The POST call and the GET call will return the same information. You make the POST call when you have not received a token from the user, and you make the GET call when you have. You do not make these calls in sequence; they are alternatives. Either way the response will be in the same format, and the action you take will be the same.

Debes guardar el token en una cookie o en tu objeto de sesión, para poder validar al usuario varias veces cada vez que acceda a diferentes direcciones URL de tu sitio web.

Ten cuidado al configurar tu cookie de token o sesión, ya que un usuario que esté esperando podría intentar acceder a otras URL de tu sitio web y no querrás que pase a ocupar un nuevo puesto al final de la cola. Por este motivo:

  1. Recomendamos almacenar el token lo antes posible, sin esperar a saber si este usuario debe permanecer en espera o no.
  2. Ten cuidado con la caducidad de la sesión. Es posible que tu aplicación cuente con un almacén de sesiones con un tiempo de espera de 20 minutos, pero el usuario podría permanecer en la sala de espera durante horas. Una cookie de sesión que solo caduque cuando el usuario cierre el navegador es una buena opción. Una cookie permanente podría ser incluso mejor.

4. When to make your first call

El objetivo de CrowdHandler es proteger tu sitio web de una carga excesiva. El propósito de realizar la comprobación de validación es garantizar que el usuario de tu sitio web realmente deba acceder a esta URL en este momento. Por lo tanto, debes realizar estas llamadas lo antes posible en la ruta de ejecución de tu código. El objetivo principal es ahorrar tiempo de ejecución y recursos del servidor. En cuanto conozcas la solicitud de la URL y puedas realizar la llamada, debes hacerlo.

5. What to do with the result

  • ¿Si el valor de «promoted» es 1? Entonces, sal del código de comprobación y vuelve al flujo normal de la aplicación. Sirve la URL como lo harías habitualmente.
  • ¿Si «promoted» es 0?, redirige al usuario a la sala de espera utilizando el slug. Utiliza una redirección HTTP 302 en caso de que el «usuario» sea un bot legítimo; esto le indica al bot que la redirección de la URL es temporal.
  • If you get a malformed response, or the API call fails... CrowdHandler cuenta con múltiples niveles de protección, pero hay son reasons this could happen and you need to respond. There could be a temporary network issue in your data center or on an internet backbone. If the process of making the API call fails, or the process of parsing a legitimate result fails, or evaluating the ascendido Si el valor falla, debes tratarlo como una excepción y gestionarlo. La forma de gestionarlo depende de ti:
    • La redirección en caso de error parte de la base de que, a falta de información contraria, el usuario debe ser puesto en cola. Si conoces el slug de tu sala de espera estándar (puede que tengas una opción predeterminada genérica con un slug fijo), podrías enviar al usuario allí. Si no lo sabes, puedes enviar al usuario a https://wait.crowdhandler.com, donde se le mostrará una plantilla genérica, se comprobará periódicamente si hay más información y se le redirigirá de nuevo a tu sitio web, o a la sala de espera adecuada, cuando se restablezca el servicio normal.
    • Trust on fail - you can decide to let the user have access to the page if the API call fails. This will depend on how regularly your site sees high-traffic and how predictable the patterns are. If you've installed CrowdHandler only for occasional, planned use, with event-specific waiting rooms, you may prefer to trust users in the event that you are not receiving well-formed responses from the CrowdHandler API.

6. Redirecting a user

Al redirigir a un usuario, debes incluir los siguientes parámetros codificados en la URL de redirección.

  1. ch-id: el token devuelto por la API.
  2. url: la URL que el usuario estaba solicitando. Si los parámetros de la cadena de consulta son importantes para ti (ya sea por motivos de marketing o seguimiento, o porque los utilizas para identificadores de productos y similares), debes asegurarte de que también se pasen como parte del parámetro «url».
  3. ch-public-key: si no conoces el slug de la sala de espera de tus usuarios, quizá porque has recibido una respuesta incorrecta o no has recibido respuesta alguna, puedes enviar tu clave pública en lugar del slug utilizando este parámetro. Esto permitirá que la sala de espera de seguridad de CrowdHandler utilice tu clave para buscar el slug correcto y gestionar la situación adecuadamente.

7. The Last Call. Logging Page Performance

PUT /responses/:id

El registro del rendimiento de tu página permite a CrowdHandler supervisar el rendimiento de tu dominio. Esto resulta útil a la hora de supervisar picos de tráfico y es fundamental para activar la función de ajuste automático.

Esta llamada es de tipo PUT y se dirige a un nuevo recurso : /responses/:id. El ID te fue facilitado como «responseID» en el resultado de la primera llamada que realizaste.

La carga útil de esta llamada tiene un aspecto similar al siguiente:

{
    "code": 200,
    "time": 2000
}
  • El código es la respuesta HTTP de la página que estás mostrando al usuario. Normalmente será 200, pero si puedes detectar códigos de error HTTP, deberías enviarlos. Esto ayudará a CrowdHandler a identificar cuándo tu sitio web tiene problemas*, lo que permitirá que la función de ajuste automático tome medidas. Si omites este parámetro, CrowdHandler utilizará el valor predeterminado 200.
  • tiempo es el tiempo que tarda tu página en cargarse, expresado en milisegundos. Puedes calcularlo de la siguiente manera:

    • dedicar un tiempo cuando recibas la solicitud por primera vez (a)

    • tómate un momento justo antes de enviar esta solicitud PUT (b)

    • restando b de a y asegurándose de que la diferencia de tiempo se exprese en milisegundos (milésimas de segundo).

      While this sounds fairly straightforward, you need to take quite a bit of care. Different languages and frameworks have different methods for tracking time in small increments, there can be differences, or performance issues, based on whether you are using VMs or bare-metal servers, and different processor types. Some frameworks have APIs specifically for tracking page performance. If you are confident, you can supply a very accurate reading to CrowdHandler. If you're less confident, simply omit this parameter. In this case CrowdHandler will do its own calculation based on the time between the initial request, and the subsequent PUT. The estimate for page load time could be impacted somewhat by network times, and is lower resolution, but the information is sufficient for a health check and is better than the wildly inaccurate value that could be supplied if you get your calculation wrong.

* Una respuesta con un código de error es gestionada por CrowdHandler de la misma forma que una solicitud que supera el tiempo máximo de respuesta. Por lo tanto, si se están devolviendo errores 500 muy rápidamente, pero la cantidad de errores supera el umbral porcentual aceptable, la función de ajuste automático reducirá el tráfico como si esas solicitudes estuvieran respondiendo por encima del umbral aceptable de carga de la página.

When to make the call.

While the initial call should be made as early as possible, this call should be made as late as possible, after you've served your page to the user. Also — it sounds obvious, but you only make this call if you actually served the URL. If you redirected the user to the waiting room, you should skip this call altogether. So after your first call there is a conditional branch between sending the redirect, or serving the page, and logging the performance.

8. Putting it all together

El siguiente pseudocódigo** reúne todos estos elementos para describir una integración sencilla, pero completa. Verás que transmite la idea más rápidamente que las largas explicaciones que hemos dado hasta ahora; no obstante, te recomendamos que consultes las notas para conocer el contexto.

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

** it's the mongrel love-child of Ruby and Python, two readable languages, with imaginary and simple APIs for issuing API calls, retrieving request data and sending responses. We hope it's easy for you to read between the lines.

Echa un vistazo a nuestro SDK de PHP para ver una biblioteca de código totalmente funcional.