Guida passo passo all'integrazione di un'API di base lato server

Questa guida spiega come realizzare un'integrazione di base dell'API lato server.

In questo modo si verificherà che l'utente del tuo sito web abbia il diritto di accedere all'URL corrente e, in caso contrario, verrà reindirizzato a una sala d'attesa.

La presente guida è destinata agli sviluppatori. Si presume che i lettori abbiano familiarità con le API e simili.

Questa integrazione utilizza le risorse pubbliche dell'API CrowdHandler, avvalendosi della chiave pubblica. È disponibile per tutti i piani, compreso quello gratuito.

1. Connessione all'API

Per prima cosa ti servirà la tua chiave pubblica. Leggi la nostra guida introduttiva all'API per ottenere la tua chiave API.

2. Effettuare la prima chiamata

POST /richieste/

Qui utilizziamo Postman per illustrare le chiamate. È un ottimo strumento per effettuare chiamate API, testare l’invio dei parametri e capire quali dati vengono restituiti mentre si realizza l’integrazione.

Stiamo utilizzando l'autenticazione di base (Basic Auth) per inviare la nostra chiave. Postman ci consentirà di inserirla una sola volta nella scheda "Autorizzazione" e di salvarla per tutte le richieste che effettueremo. La chiave va inserita nel campo "Nome utente". La password viene ignorata.

Ora che abbiamo configurato l'intestazione di autenticazione, inizieremo effettuando una richiesta POST a https://api.crowdhandler.com/v1/requests. Questa chiamata serve per avviare una nuova richiesta a un URL del tuo sito, per verificare se a questo utente debba essere concesso l'accesso o se debba essere reindirizzato.

Il post call richiede il seguente payload JSON:

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

Esaminiamo questi parametri uno per uno:

  • url - Si tratta dell'URL a cui l'utente sta tentando di accedere. La fonte da cui lo si ottiene dipende dall'applicazione, dal linguaggio e dal framework utilizzati. Potrebbe trattarsi di una variabile CGI, oppure potresti disporre di una sorta di front-controller/router. L'URL deve essere completo, compreso il protocollo. CrowdHandler supporta solo HTTPS.
  • ip - Questo è l'indirizzo IP della richiesta dell'utente. Anche in questo caso, la fonte da cui recuperare questa informazione dipenderà dal linguaggio di programmazione e dal framework utilizzati. L'indirizzo IP è obbligatorio. Viene utilizzato per la prevenzione delle frodi e il rilevamento dei bot.
  • agent - questa è la stringa dell'user agent. È anch'essa obbligatoria. È necessario recuperarla dall'intestazione HTTP User-Agent.
  • lang - è la lingua preferita dall'utente. Si tratta di un parametro facoltativo che può aiutare a identificare gli agenti fraudolenti. È possibile ricavarlo dall'intestazione HTTP Accept-Language.

Se tutto va bene e l'URL che hai fornito è protetto da una "sala d'attesa", dovresti ricevere una risposta simile a questa:

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

Analisi del risultato:

  • Il token è l'identificatore dell'utente. All'inizio non ne avevamo uno, quindi abbiamo effettuato una richiesta POST, che non ne richiede uno, e questo significa che abbiamo ricevuto un nuovo token con la nostra prima richiesta.
  • Il valore "promoted" è l'attributo principale che ci interessa. Un valore pari a 0 indica che l'utente associato a questo token deve attendere in coda per l'URL specificato. Un valore pari a 1 indica che l'utente non deve attendere in coda. Questo token ha un valore "promoted" pari a 0, il che indica che l'utente deve attendere in coda.
  • slug: lo slug indica l'indirizzo della sala d'attesa. L'indirizzo completo della sala d'attesa sarà https://wait.crowdhandler.com/your-slug
  • responseID è un identificativo univoco che identifica la risposta appena ricevuta. Potremmo utilizzarlo in seguito per registrare le prestazioni di questa richiesta tramite l'API CrowdHandler.
  • Gli altri attributi sono interessanti e possono essere utili per la risoluzione dei problemi e il debug, ma non è necessario utilizzarne nessuno per una semplice integrazione. Se sei interessato a utilizzarli per altri motivi, puoi consultarne il significato nella documentazione dell'API.

Quindi, se la nostra integrazione ricevesse questa specifica risposta, vorremmo reindirizzare l'utente alla sala d'attesa: https://wait.crowdhandler.com/queen-victoria-hall.

Vedi qualcos’altro?

Potresti non ottenere la risposta di esempio riportata sopra. Se la tua risposta risulta notevolmente diversa, a seconda di ciò che vedi, potrebbe essersi verificato uno dei seguenti problemi:

  • Un errore? Ciò indicherebbe che c'è qualcosa che non va nei parametri della tua richiesta. L'errore dovrebbe indicarti dove stai sbagliando.
  • Nessuna informazione sulla sala d'attesa? Se invii URL che non rientrano nell'ambito di nessuna delle tue sale d'attesa, riceverai un token e il parametro `promoted` avrà il valore 1, ma non otterrai alcuna informazione sulla sala d'attesa. Potresti provare a configurare una sala d'attesa generica, per facilitare i tuoi test.
  • Nessun token? Se provi a testare la chiamata utilizzando URL su nomi di dominio che non sono nemmeno registrati sul tuo account CrowdHandler, riceverai comunque 1 come valore restituito (non siamo responsabili della protezione di quel dominio, quindi per quanto ci riguarda puoi procedere tranquillamente!). Tuttavia, non riceverai alcun token.
  • Se ricevi lo stato 3, significa che il tuo indirizzo IP è stato bloccato. Ciò può accadere quando si effettuano numerose richieste all'API pubblica dallo stesso indirizzo IP ed è un fenomeno comune durante il collaudo di un'integrazione. Accedi al pannello di amministrazione, individua il tuo indirizzo IP (alla voce Domini → IP) e modifica lo stato del tuo indirizzo IP impostandolo su "Ignora".

Ok, abbiamo effettuato la nostra prima chiamata, sappiamo qual è il risultato e come dobbiamo reagire. Parleremo dei dettagli su come gestire queste informazioni dopo aver trattato la prossima chiamata.

3. La tua seconda chiamata

GET /richieste/:token

Nel primo esempio non avevamo alcun token utente. La chiamata POST non riceve un token, ma ne restituisce uno. Quindi questa è la richiesta da effettuare quando l'utente sul tuo sito non ha un token. Ma se l'utente è arrivato sul tuo sito perché si trovava nella sala d'attesa ed è riuscito a superare la fase di attesa, allora avrà un token. In tal caso, devi assicurarti di utilizzarlo e conservarlo per verificare la sua identità. Perché se gliene assegni uno nuovo, molto probabilmente finirà di nuovo in coda.

Dove posso trovare il token?

Quando CrowdHandler reindirizza gli utenti al tuo sito, aggiunge il token all'URL. Il token viene inserito come parametro della stringa di query denominato ch-id. Ad esempio: https://yoursite.com/your-url?ch-id=tok_S0mET0k3n. Devi quindi verificare la presenza del token in quel parametro dell'URL. Se lo trovi, effettua la richiesta GET anziché quella POST.

Ma non è tutto!

L'utente continuerà quindi a cliccare su molti altri link presenti sul tuo sito web. Pertanto, per assicurarti che l'utente non si ritrovi nuovamente nella "sala d'attesa" , devi impostare un cookie di sessione ogni volta che ricevi il token e controllare il cookie ogni volta che non riesci a trovare "ch-id" nell'URL. Se ancora non lo trovi, invia la richiesta POST.

I token hanno una scadenza?

È vero. Tuttavia, ogni volta che invii un token non valido, CrowdHandler ignorerà quel token, tratterà la richiesta come se non fosse stato impostato alcun token e ti invierà un nuovo token, oltre a verificare la tua richiesta. Ciò significa che i token si auto-eliminano e non devi preoccuparti di tenerne traccia o della loro scadenza. Ma significa anche che il token che ricevi in risposta non è necessariamente quello che hai inviato. Devi considerare attendibile il token che ricevi rispetto a quello che hai inviato, quindi imposta il cookie ogni volta.

Devo controllare prima il cookie o il parametro dell'URL?

Il parametro URL. In situazioni complesse, è possibile che l'utente disponga di un nuovo token nella sala d'attesa, ma che sul tuo sito sia ancora memorizzato un cookie obsoleto. Se l'utente proviene dalla sala d'attesa, il nuovo token sarà presente nell'URL; dovresti quindi considerare attendibile quel token, piuttosto che quello potenzialmente obsoleto che avevi precedentemente impostato come cookie.

Ovviamente, non bisogna interpretare l'assenza del parametro "ch-id" come un'istruzione a cancellare eventuali cookie esistenti. Quindi controllate attentamente.

E allora... la telefonata:

Il payload è lo stesso della richiesta POST, ma poiché in questo caso si tratta di una richiesta GET, inviamo i parametri come parametri GET, non come JSON grezzo. L'URL è cambiato. Questa volta il token fa parte dell'URL.

La risposta è molto simile alla richiesta POST. L'unica differenza è che questa volta possiamo notare che il token che abbiamo ricevuto è lo stesso che abbiamo inviato. Le decisioni che la nostra integrazione deve prendere, sulla base di questi dati, sono esattamente le stesse previste per la richiesta POST.

In conclusione

La richiesta POST e quella GET restituiranno le stesse informazioni. Si effettua la richiesta POST quando non si è ricevuto un token dall'utente, mentre si effettua la richiesta GET quando lo si è ricevuto. Queste richieste non vengono effettuate in sequenza, ma sono alternative. In entrambi i casi la risposta avrà lo stesso formato e l'azione da intraprendere sarà la stessa.

È necessario memorizzare il token in un cookie o nell'oggetto di sessione, in modo da poter verificare l'identità dell'utente ogni volta che accede a diversi URL del sito.

Fai attenzione quando imposti il cookie token o la sessione, perché un utente in attesa potrebbe provare ad accedere ad altri URL del tuo sito e non vorrai certo che venga reinserito in fondo alla coda. Per questo motivo:

  1. Si consiglia di archiviare il token il prima possibile, senza aspettare di sapere se l'utente debba rimanere in attesa o meno.
  2. Presta attenzione alla scadenza della sessione. La tua applicazione potrebbe disporre di un archivio sessioni con un timeout di 20 minuti, ma l'utente potrebbe rimanere nella sala d'attesa per ore. Un cookie di sessione che scade solo quando l'utente chiude il browser è una buona soluzione. Un cookie permanente potrebbe essere ancora meglio.

4. Quando effettuare la prima chiamata

Lo scopo di CrowdHandler è proteggere il tuo sito da un carico eccessivo. Lo scopo del controllo di validità è garantire che l’utente del tuo sito stia effettivamente accedendo a quell’URL in quel momento. Pertanto, dovresti effettuare queste chiamate il prima possibile nel percorso di esecuzione del tuo codice. L’obiettivo principale è risparmiare tempo di esecuzione e risorse del server. Non appena conosci l’URL della richiesta e sei in grado di effettuare la chiamata, dovresti farlo.

5. Cosa fare con il risultato

  • Se il valore di "promoted" è 1, esci dal codice di verifica e torna al flusso standard dell'applicazione. Visualizza l'URL come faresti normalmente.
  • Se "promoted" è pari a 0, reindirizzare l'utente alla sala d'attesa utilizzando lo slug. Utilizzare un reindirizzamento HTTP 302 nel caso in cui l'"utente" sia un bot legittimo; in questo modo si comunica al bot che il reindirizzamento dell'URL è temporaneo.
  • Se ricevi una risposta non valida o se la chiamata all'API non va a buon fine... CrowdHandler dispone di numerosi livelli di protezione, ma c'è sono motivi per cui ciò potrebbe verificarsi e per cui è necessario intervenire. Potrebbe esserci un problema temporaneo di rete nel proprio data center o sulla dorsale Internet. Se il processo di effettuazione della chiamata API fallisce, oppure se fallisce il processo di analisi di un risultato valido, oppure se la valutazione del promosso Se il valore non è corretto, devi considerarlo come un'eccezione e gestirlo di conseguenza. Il modo in cui gestirlo dipende da te:
    • Il reindirizzamento in caso di errore presuppone che, in mancanza di indicazioni diverse, l'utente debba essere messo in coda. Se conosci lo slug della tua sala d'attesa standard (potresti avere una pagina predefinita generica con uno slug stabile), puoi indirizzare l'utente lì. Se non lo conosci, puoi indirizzare l'utente a https://wait.crowdhandler.com, dove all'utente verrà presentato un modello generico, verranno effettuati controlli periodici per ottenere informazioni più precise e, una volta ripristinato il normale servizio, verrà reindirizzato al tuo sito o alla sala d'attesa appropriata.
    • Affidarsi in caso di errore: puoi decidere di consentire all'utente l'accesso alla pagina se la chiamata all'API fallisce. Ciò dipenderà dalla frequenza con cui il tuo sito registra picchi di traffico e dalla prevedibilità di tali andamenti. Se hai installato CrowdHandler solo per un utilizzo occasionale e pianificato, con sale d'attesa specifiche per determinati eventi, potresti preferire affidarti agli utenti nel caso in cui non riceviate risposte correttamente formate dall'API di CrowdHandler.

6. Reindirizzamento di un utente

Quando si reindirizza un utente, è necessario specificare i seguenti parametri codificati in formato URL nell'URL di reindirizzamento.

  1. ch-id: il token restituito dall'API.
  2. url: l'URL richiesto dall'utente. Se i parametri della stringa di query sono importanti per te (sia per motivi di marketing o tracciamento, sia perché li utilizzi per gli ID dei prodotti o simili), devi assicurarti che vengano passati anche come parte del parametro url.
  3. ch-public-key: se non conosci lo slug della sala d'attesa per i tuoi utenti, magari perché hai ricevuto una risposta non valida o nessuna risposta, puoi inviare la tua chiave pubblica al posto dello slug, utilizzando questo parametro. Ciò consentirà alla sala d'attesa di sicurezza di CrowdHandler di utilizzare la tua chiave per individuare lo slug corretto e gestire la situazione in modo appropriato.

7. L'ultima chiamata. Registrazione delle prestazioni della pagina

PUT /responses/:id

La registrazione delle prestazioni della tua pagina consente a CrowdHandler di monitorare le prestazioni del tuo dominio. Ciò risulta utile per monitorare i picchi di traffico ed è fondamentale per abilitare la funzione di ottimizzazione automatica.

Questa chiamata è di tipo PUT e viene indirizzata a una nuova risorsa /responses/:id. L'ID ti è stato fornito come responseID nel risultato della prima chiamata che hai effettuato.

Il payload di questa chiamata è più o meno il seguente:

{
    "code": 200,
    "time": 2000
}
  • Il codice rappresenta la risposta HTTP della pagina che stai fornendo all'utente. In genere è 200, ma se sei in grado di intercettare i codici di errore HTTP dovresti inviarli. Ciò aiuterà CrowdHandler a identificare quando il tuo sito web presenta difficoltà*, consentendo ad Autotune di intervenire. Se ometti questo parametro, CrowdHandler utilizzerà il valore predefinito 200.
  • tempo è il tempo di caricamento della tua pagina in millisecondi. Puoi calcolarlo nel modo seguente:

    • dedicare un po’ di tempo non appena ricevi la richiesta (a)

    • dedicare un po’ di tempo proprio prima di inviare questo PUT (b)

    • sottraendo b da a e assicurandosi che la differenza di tempo sia espressa in millisecondi (millesimi di secondo).

      Sebbene possa sembrare piuttosto semplice, è necessario prestare molta attenzione. Lingaggi e framework diversi utilizzano metodi diversi per misurare il tempo in piccoli incrementi; possono esserci differenze o problemi di prestazioni a seconda che si utilizzino macchine virtuali o server bare-metal, nonché a seconda dei diversi tipi di processore. Alcuni framework dispongono di API specifiche per il monitoraggio delle prestazioni delle pagine. Se si è sicuri, è possibile fornire a CrowdHandler una lettura molto accurata. Se invece non si è sicuri, è sufficiente omettere questo parametro. In questo caso, CrowdHandler effettuerà il proprio calcolo in base al tempo intercorso tra la richiesta iniziale e il successivo PUT. La stima del tempo di caricamento della pagina potrebbe risentire in parte dei tempi di rete e presenta una risoluzione inferiore, ma le informazioni sono sufficienti per un controllo dello stato di salute e sono comunque migliori del valore estremamente impreciso che si otterrebbe in caso di calcolo errato.

* Una risposta con un codice di errore viene gestita da CrowdHandler allo stesso modo di una richiesta che supera il tempo massimo di risposta impostato. Pertanto, se si generano errori 500 a un ritmo molto elevato, ma il numero di errori supera la soglia percentuale accettabile, la funzione di regolazione automatica rallenterà il traffico come se tali richieste superassero la soglia accettabile di caricamento della pagina.

Quando effettuare la chiamata.

Sebbene la chiamata iniziale debba essere effettuata il prima possibile, questa chiamata va invece effettuata il più tardi possibile, dopo aver visualizzato la pagina all’utente. Inoltre — anche se può sembrare ovvio — questa chiamata va effettuata solo se l’URL è stato effettivamente visualizzato. Se l’utente è stato reindirizzato alla pagina di attesa, questa chiamata va saltata del tutto. Quindi, dopo la prima chiamata, c’è un ramo condizionale tra l’invio del reindirizzamento o la visualizzazione della pagina e la registrazione delle prestazioni.

8. Mettere tutto insieme

Il seguente pseudocodice** riassume il tutto per descrivere un'integrazione semplice ma completa. Noterete che rende l'idea più rapidamente rispetto alle lunghe spiegazioni fornite finora, ma è comunque consigliabile consultare le note per contestualizzare il tutto.

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

** È il frutto di un incrocio tra Ruby e Python, due linguaggi di facile lettura, con API immaginarie e semplici per effettuare chiamate API, recuperare i dati delle richieste e inviare risposte. Speriamo che vi risulti facile cogliere il senso tra le righe.

Dai un'occhiata al nostro SDK PHP per una libreria di codice completamente funzionante.