Integración básica de una API en el servidor

Esta guía explica cómo lograr una integración básica de API del lado del servidor.

Esto validará que el usuario de su sitio web tiene derecho a acceder a la URL actual y lo redirigirá a una sala de espera en caso contrario.

Esta guía está dirigida a desarrolladores. Se supone que están familiarizados con las API, etc.

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

1. Conexión a la API

Primero necesitarás tu clave pública. Lea nuestra introducción a la API para obtener acceso a su clave api.

2. Hacer la primera llamada

POST /solicitudes/

Aquí estamos usando Postman para demostrar las llamadas. Es una gran manera de hacer llamadas a la API, para probar el envío de parámetros y entender lo que está volviendo como usted está poniendo su integración juntos.

Estamos usando Basic Auth para enviar nuestra clave. Postman nos permitirá introducirla una vez en la pestaña de autorización, y guardarla para todas las llamadas que hagamos. La clave va en el campo Nombre de usuario. La contraseña se ignora. 

Ahora que tenemos nuestra cabecera de autenticación configurada vamos a empezar haciendo una llamada POST a https://api.crowdhandler.com/v1/requests. Esta llamada se utiliza para iniciar una nueva solicitud a una URL en tu sitio, para ver si este usuario debe obtener acceso o ser redirigido. 

La llamada post espera la siguiente carga 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. De dónde se obtiene depende de la aplicación, el lenguaje y el framework. Puede ser una variable CGI, o puede tener algún tipo de controlador/enrutador frontal. La URL debe estar completa, incluyendo el protocolo. CrowdHandler sólo soporta HTTPS. 
• ip - Esta es la dirección IP de la solicitud del usuario. Una vez más, de dónde se obtiene esta información dependerá de su idioma y el marco. La IP es necesaria. Se utiliza para la prevención del fraude y la detección de bots.
• agent - es la cadena del agente de usuario. También es obligatorio. Deberías recuperarlo de la cabecera HTTP User-Agent.
• lang - es el idioma preferido por el usuario. Es un parámetro opcional, y puede ayudar a identificar agentes fraudulentos. Se puede obtener de la cabecera HTTP Accept-Language.

Si todo va bien, y la url que has proporcionado está protegida por una sala de espera, deberías recibir una respuesta parecida a ésta:

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

Caminando por la salida:

• token token es el identificador del usuario. No teníamos uno para empezar, así que hicimos una petición POST, que no requiere uno, y esto significa que recibimos un nuevo token con nuestro primer éxito.
• promoted es el atributo principal que nos interesa. Un valor de 0 significa que el usuario con este token necesita hacer cola para la url especificada. Un valor de 1 significa que el usuario no necesita hacer cola. Este token tiene un valor promocionado 0 que indica que necesitamos que este usuario haga cola. 
• slug el 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 acaba de recibir. Podemos utilizarlo más tarde, para registrar el rendimiento de esta solicitud con la API CrowdHandler.
• los otros atributos son interesantes, y pueden ayudar en 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 sus significados en la documentación de la API. 

Así que si nuestra integración recibiera esta respuesta en particular, 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 obtenga la respuesta del modelo anterior. Si su respuesta es significativamente diferente, una de las siguientes cosas puede haber ido mal dependiendo de lo que está viendo: 

• ¿Un error? Esto indicaría que hay algo mal en los parámetros de tu petición. El error debería indicarte qué estás haciendo mal.
• ¿No hay información de la sala de espera? Si estás enviando URLs que no entran en el ámbito de ninguna de tus salas de espera, recibirás un token y promovido tendrá el valor de 1, pero no obtendrás información de la sala de espera de vuelta. Puede intentar crear una sala de espera general para facilitar las pruebas.
• ¿No tiene token? Si intenta probar la llamada utilizando direcciones URL de nombres de dominio que ni siquiera están registrados en su cuenta CrowdHandler, seguirá recibiendo 1 como valor promocionado (no somos responsables de proteger ese dominio, así que por lo que a nosotros respecta, puede continuar). Pero no recibirá un token. 
• Si recibes el estado 3, significa que tu IP ha sido bloqueada. Esto puede ocurrir cuando haces muchas peticiones a la API pública desde la misma IP y es común cuando se prueba una integración. Accede al panel de administración, busca tu IP (en dominios > IPs) y cambia el estado de tu IP a ignorar. 

Bien, hemos hecho nuestra primera llamada, sabemos cuál es la salida y cómo se supone que debemos reaccionar ante ella. Vamos a hablar de los detalles de la manipulación de esta información después de cubrir la siguiente llamada.

3. Su segunda llamada

GET /peticiones/:token

En el primer ejemplo no teníamos token de usuario. La llamada POST no recibe un token, te devuelve uno. Así que esa es la llamada a hacer cuando el usuario en su sitio no tiene token. Pero si el usuario ha aterrizado en su sitio porque estaban en la sala de espera y lo hizo a través de, entonces tendrán un token. En ese caso, querrás asegurarte de usarlo y retenerlo para comprobarlo. Porque si les das uno nuevo, lo más probable es que acaben de nuevo en la cola. 

¿Dónde puedo encontrar la ficha?

Cuando CrowdHandler redirige a los usuarios a su sitio, añade el token a la url. Va como un parámetro de cadena de consulta llamado ch-id. Por ejemplo https://yoursite.com/your-url?ch-id=tok_S0mET0k3n. Así que tienes que comprobar ese parámetro URL para un token. Y si lo encuentras allí, haces la llamada GET en lugar de la llamada POST.

Pero eso no es todo.

A continuación, el usuario hará clic en muchos otros enlaces de su sitio web. Así que para asegurarse de que el usuario no se encuentra de nuevo en la sala de espera, es necesario establecer una cookie de sesión, cada vez que reciba el token de vuelta, y es necesario comprobar la cookie, cada vez que no se puede encontrar ch-id en la URL. Si aún así no lo encuentra, envíe la solicitud POST.

¿Caducan las fichas?

Lo hacen. Pero siempre que pases un token inválido, CrowdHandler ignorará ese token, tratará la solicitud como si no se hubiera establecido ningún token, y te devolverá un nuevo token además de comprobar tu solicitud. Esto significa que los tokens se limpian solos y no tienes que preocuparte por el seguimiento y la caducidad de los tokens. Pero también significa que el token que recibes no es necesariamente el que enviaste. Necesitas confiar en el token que recibes sobre el que enviaste, así que configura la cookie cada vez.

¿Debo comprobar primero la cookie o el parámetro URL?

El parámetro URL. En situaciones complejas es posible que tu usuario tenga un nuevo token en la sala de espera, pero todavía tenga una vieja cookie almacenada en tu sitio. Si el usuario es enviado desde la sala de espera, el nuevo token estará en la URL, deberías confiar en ese token, sobre el potencialmente obsoleto que previamente estableciste como cookie. 

Por supuesto, no debe utilizar la ausencia del parámetro ch-id como una instrucción para borrar cualquier cookie existente. Así que compruébalo con cuidado.

Entonces... la llamada:

La carga útil es la misma que para la solicitud POST, pero como se trata de una solicitud GET, enviamos los parámetros como parámetros GET, no como JSON sin procesar. La URL ha cambiado. Esta vez el token forma parte de la URL.

La respuesta, tiene un aspecto muy similar a la petición POST. Excepto que esta vez podemos ver que el token que hemos recibido es el mismo que enviamos. Las decisiones que nuestra integración necesita tomar, basadas en estos datos, son exactamente las mismas que para la petición POST.

En conclusión

La llamada POST y la llamada GET devolverán la misma información. La llamada POST se realiza cuando no se ha recibido un token del usuario, y la llamada GET cuando sí se ha recibido. Estas llamadas no se hacen en secuencia, son alternativas. En cualquier caso, la respuesta tendrá el mismo formato y la acción que tomes será la misma. 

Necesita almacenar el token en una cookie, o en su objeto de sesión, para poder validar al usuario repetidamente a medida que accede a diferentes urls en su sitio.

Ten cuidado al configurar tu cookie o sesión de token, porque un usuario en espera puede intentar acceder a otras urls de tu sitio y no querrás darle una nueva posición al final de la cola. Por esta razón:

1. Recomendamos almacenar el token a la primera oportunidad, no esperar hasta saber si este usuario debe esperar o no. 
2. Ten cuidado con la caducidad de la sesión. Su aplicación puede tener un almacén de sesión con un tiempo de espera de 20 minutos, pero el usuario podría estar en la sala de espera durante horas. Una cookie de sesión que sólo expira cuando el usuario cierra su navegador es una buena apuesta. Una cookie permanente puede ser incluso mejor. 

4. Cuándo hacer la primera llamada

El propósito de CrowdHandler es proteger su sitio de una carga excesiva. El propósito de hacer la comprobación de validación es asegurar que el usuario en su sitio realmente debería estar accediendo a esta URL en este momento. Así que usted debe hacer estas llamadas en la primera oportunidad posible en su ruta de ejecución de código. El propósito es ahorrar tiempo de ejecución y recursos del servidor. Tan pronto como conozcas la petición url y seas capaz de hacer la llamada deberías hacerla.

5. Qué hacer con el resultado

• Si promovido es 1? entonces salga del código de comprobación y vuelva a su flujo de aplicación estándar. Sirva la URL como lo haría normalmente.
• Si promoted es 0? entonces redirige al usuario a la sala de espera usando 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 malformada, o la llamada a la API falla... CrowdHandler tiene muchas capas de protección, pero hay son razones por las que esto puede ocurrir y hay que reaccionar. Podría haber un problema temporal de red en su centro de datos o en una red troncal de Internet. Si el proceso de realizar la llamada a la API falla, o el proceso de analizar un resultado legítimo falla, o la evaluación de la promovido falla, debe tratarla como una excepción y gestionarla. La forma de gestionarlo depende de usted:
  • Redirigir al fallar presume, si no lo sabes mejor, que el usuario debe ser puesto en cola. Si conoces el slug de tu sala de espera estándar (puede que tengas un catch-all por defecto con un slug estable) entonces podrías enviar al usuario allí. Si no lo sabe, puede enviar al usuario a https://wait.crowdhandler.comdonde se servirá al usuario una plantilla genérica, se sondeará regularmente para obtener mejor información y se le dirigirá de nuevo a su sitio, o a la sala de espera apropiada, cuando se reanude el servicio normal.
  • Confiar en caso de fallo: puede decidir permitir que el usuario acceda a la página si falla la llamada a la API. Esto dependerá de la regularidad con la que su sitio tenga un tráfico elevado y de lo predecibles que sean los patrones. Si ha instalado CrowdHandler sólo para un uso ocasional y planificado, con salas de espera para eventos específicos, puede que prefiera confiar en los usuarios en caso de que no reciba respuestas bien formadas de la API de CrowdHandler.

6. Redirigir a un usuario

Al redirigir a un usuario, debe proporcionar los siguientes parámetros codificados en url 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 cadena de consulta son importantes para usted (ya sea por razones de marketing/seguimiento, o porque los utiliza para ID de productos y similares), entonces debe asegurarse de que también se pasan como parte del parámetro url. 
3. ch-public-key: si no conoce el slug de la sala de espera de sus usuarios, tal vez porque recibió una respuesta malformada, o ninguna respuesta, entonces puede enviar su clave pública en lugar de un slug, utilizando este parámetro. Esto permitirá a la sala de espera de la red de seguridad de CrowdHandler utilizar su clave para buscar el slug correcto, y manejarlo apropiadamente.

7. La última llamada. Registro del rendimiento de la página

PUT /respuestas/:id

Registrar el rendimiento de su página permite a CrowdHandler monitorizar el rendimiento de su dominio. Esto es útil cuando se controla el tráfico pesado, y crítico para habilitar la función de ajuste automático.

Esta llamada es un PUT. y va a un nuevo recurso /responses/:id. El ID se le proporcionó como responseID en el resultado de la primera llamada que hizo.

La carga útil de esta llamada tiene este aspecto:

{
    "code": 200,
    "time": 2000
}

• es la respuesta HTTP para la página que está sirviendo al usuario. Normalmente sería 200, pero si puede atrapar códigos de error http, debería enviarlos. Esto ayudará a CrowdHandler a identificar cuándo su sitio web tiene problemas*, permitiendo que autotune tome medidas. Si omite este parámetro, CrowdHandler enviará por defecto 200.
• tiempo es el tiempo de carga de su página en milisegundos. Usted puede calcular esto por:
  • en el momento en que reciba su solicitud por primera vez (a)
  • tomando el tiempo justo antes de enviar este PUT (b)
  • restando b de a y asegurándose de que la diferencia de tiempo se expresa en milisegundos (milésimas de segundo).
    
    Aunque esto parece bastante sencillo, hay que tener bastante cuidado. Diferentes lenguajes y frameworks tienen diferentes métodos para el seguimiento del tiempo en pequeños incrementos, puede haber diferencias, o problemas de rendimiento, en función de si está utilizando máquinas virtuales o servidores bare-metal, y diferentes tipos de procesador. Algunos frameworks tienen APIs específicas para el seguimiento del rendimiento de las páginas. Si está seguro, puede proporcionar una lectura muy precisa a CrowdHandler. Si no está tan seguro, simplemente omita este parámetro. En este caso CrowdHandler hará su propio cálculo basado en el tiempo entre la petición inicial, y la subsiguiente 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 es de menor resolución, pero la información es suficiente para una comprobación de la salud y es mejor que el valor tremendamente inexacto que podría ser suministrado si se equivoca en el cálculo.

* una respuesta con un código de error, es manejada por CrowdHandler de la misma manera que lo es una petición que excede su tiempo máximo de respuesta. Así que si estás sirviendo 500 errores muy rápido, pero la cantidad de errores está excediendo tu umbral de % aceptable, autotune ralentizará el tráfico como si esas peticiones estuvieran respondiendo por encima de tu umbral de carga de página aceptable. 

Cuándo hacer la llamada.

Mientras que la llamada inicial debe hacerse lo antes posible, esta llamada debe hacerse lo más tarde posible, después de haber servido la página al usuario. También - suena obvio, pero sólo se hace esta llamada si realmente sirvió la URL. Si ha redirigido al usuario a la sala de espera, debería omitir esta llamada. Así que después de tu primera llamada hay una rama condicional entre enviar la redirección, o servir la página, y registrar el rendimiento.

8. Puesta en común

El siguiente pseudocódigo** lo reúne todo 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, pero, no obstante, deberías consultar 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 mestizo hijo predilecto de ruby y python, dos lenguajes legibles, con APIs imaginarias y sencillas para emitir llamadas a la API, recuperar datos de peticiones y enviar respuestas. Esperamos que te resulte fácil leer entre líneas.

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