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

En esta guía se explica cómo llevar a cabo una integración básica de una API del lado del servidor.

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. Conexión a la

En primer lugar, necesitarás tu clave pública. Lee nuestraintroducción a la API en para obtener tu clave API.

2. Cómo hacer tu primera

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.

Estamos utilizando la autenticación básica para enviar nuestra clave. Postman nos permite introducirla una sola vez en la pestaña «Autorización» y guardarla para todas las llamadas que realicemos. La clave se introduce en el campo «Nombre de usuario». El campo «Contraseña» se ignora.

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: esta es la URL a la que tu usuario está intentando acceder. La forma de obtenerla depende de tu aplicación, lenguaje y marco de trabajo. Puede ser una variable CGI, o quizá dispongas de algún tipo de controlador frontal o enrutador. La URL debe estar completa, incluyendo el protocolo. CrowdHandler solo admite 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: es el idioma preferido del usuario. Se trata de un parámetro opcional que puede ayudar a identificar a los agentes fraudulentos. Se puede obtener del encabezado HTTP «Accept-Language».

Si todo va bien y la URL que has facilitado está protegida por una sala de espera, deberías recibir una respuesta similar a esta:

{
    "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.
  • El valor de «promoted» es el atributo principal que nos interesa. Un valor de 0 significa que el usuario con este token debe ponerse en cola para la URL especificada. Un valor de 1 significa que el usuario no necesita ponerse en cola. Este token tiene un valor de «promoted» igual a 0, lo que indica que este usuario debe ponerse en cola.
  • slug the slug, indica la dirección de la sala de espera. La dirección completa de la sala de espera será 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.

¿Ves algo más?

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.
  • Si te aparece el estado 3, significa que tu dirección IP ha sido bloqueada. Esto puede ocurrir cuando se realizan muchas solicitudes a la API pública desde la misma dirección IP, y es habitual al probar una integración. Inicia sesión en el panel de administración, busca tu dirección IP (en «Dominios > IP») y cambia el estado de tu dirección IP a «ignorar».

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. Tu segunda

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.

¿Dónde puedo encontrar el token?

Cuando CrowdHandler redirige a los usuarios a tu sitio web, añade el token a la URL. Se incluye como un parámetro de cadena de consulta denominado «ch-id». Por ejemplo: https://yoursite.com/your-url?ch-id=tok_S0mET0k3n. Por lo tanto, debes comprobar si ese parámetro de la URL contiene un token. Y, si lo encuentras allí, debes realizar una llamada GET en lugar de una llamada POST.

¡Pero eso no es todo!

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.

¿Caducan los tokens?

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.

¿Debería comprobar primero la cookie o el parámetro de la URL?

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.

Y entonces... la llamada:

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.

En

Las llamadas POST y GET devolverán la misma información. Se realiza la llamada POST cuando aún no se ha recibido un token del usuario, y la llamada GET cuando ya se ha recibido. Estas llamadas no se realizan de forma secuencial, sino que son alternativas. En cualquier caso, la respuesta tendrá el mismo formato y la acción que se lleve a cabo será la misma.

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. ¿Cuándo hacer la primera

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. ¿Qué hacer con el

  • ¿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.
  • Si recibes una respuesta con un formato incorrecto o la llamada a la API falla... CrowdHandler cuenta con múltiples niveles de protección, pero hay son Hay varias razones por las que esto podría ocurrir y a las que debes responder. Podría tratarse de un problema temporal de red en tu centro de datos o en una red troncal de Internet. Si falla el proceso de realizar la llamada a la API, o falla el proceso de analizar un resultado válido, o al evaluar el 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.
    • Confiar en caso de fallo: puedes decidir permitir que el usuario acceda a la página si la llamada a la API falla. Esto dependerá de la frecuencia con la que tu sitio web registre picos de tráfico y de lo predecibles que sean dichos patrones. Si has instalado CrowdHandler únicamente para un uso ocasional y planificado, con salas de espera específicas para cada evento, quizá prefieras confiar en los usuarios en caso de que no recibas respuestas bien formadas de la API de CrowdHandler.

6. Redirigir a un

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. La última llamada. Registro del rendimiento de la página

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).

      Aunque esto parezca bastante sencillo, hay que tener bastante cuidado. Los distintos lenguajes y marcos de trabajo tienen métodos diferentes para medir el tiempo en pequeños incrementos; además, pueden surgir diferencias o problemas de rendimiento dependiendo de si se utilizan máquinas virtuales o servidores físicos, así como de los distintos tipos de procesadores. Algunos marcos de trabajo cuentan con API específicas para medir el rendimiento de las páginas. Si te sientes seguro, puedes proporcionar una lectura muy precisa a CrowdHandler. Si no te sientes tan seguro, simplemente omite este parámetro. En ese caso, CrowdHandler realizará su propio cálculo basándose en el tiempo transcurrido entre la solicitud inicial y la posterior PUT. La estimación del tiempo de carga de la página podría verse afectada en cierta medida por los tiempos de red y tiene una resolución menor, pero la información es suficiente para una comprobación de estado y es mejor que el valor tremendamente inexacto que se podría proporcionar si el cálculo fuera erróneo.

* 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.

Cuándo llamar.

Aunque la llamada inicial debe realizarse lo antes posible, esta llamada debe realizarse lo más tarde posible, una vez que hayas mostrado la página al usuario. Además —aunque parezca obvio—, solo debes realizar esta llamada si realmente has mostrado la URL. Si has redirigido al usuario a la sala de espera, debes omitir esta llamada por completo. Así pues, tras la primera llamada, hay una ramificación condicional entre enviar la redirección o mostrar la página y registrar el rendimiento.

8. Poniéndolo todo en su

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

** Es el hijo bastardo de Ruby y Python, dos lenguajes fáciles de leer, con interfaces de programación de aplicaciones (API) imaginarias y sencillas para realizar llamadas a la API, recuperar datos de las solicitudes y enviar respuestas. Esperamos que te resulte fácil leer entre líneas.

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