Passaggio di un'integrazione API di base lato server

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

Questo convaliderà che l'utente sul vostro sito web abbia il diritto di accedere all'URL corrente e, in caso contrario, lo reindirizzerà a una sala d'attesa.

Questa guida è destinata agli sviluppatori. Presuppone una certa familiarità con le API e così via.

Questa integrazione utilizza le risorse pubbliche dell'API di CrowdHandler, utilizzando la chiave pubblica. È disponibile per qualsiasi piano, compreso il livello gratuito.

1. Connessione all'API

Per prima cosa è necessaria la chiave pubblica. Leggete la nostra introduzione all'API per ottenere l'accesso alla vostra chiave API.

2. Effettuare la prima chiamata

POST /richieste/

Per dimostrare le chiamate, usiamo Postman. È un ottimo modo per effettuare chiamate API, testare l'invio di parametri e capire cosa viene restituito mentre si realizza l'integrazione.

Utilizziamo Basic Auth per inviare la nostra chiave. Postman ci consentirà di inserirla una sola volta nella scheda Autorizzazione e di salvarla per tutte le chiamate che effettueremo. La chiave va nel campo Nome utente. La password viene ignorata. 

Ora che abbiamo impostato l'intestazione di autenticazione, iniziamo a fare una chiamata POST a https://api.crowdhandler.com/v1/requests. Questa chiamata è usata per avviare una nuova richiesta a un URL del sito, per vedere se l'utente deve avere accesso o essere reindirizzato. 

La chiamata post si aspetta 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:

• url - È l'url a cui l'utente sta cercando di accedere. Il punto di partenza dipende dall'applicazione, dal linguaggio e dal framework. Può essere una variabile CGI o un qualche tipo di front controller/router. L'URL deve essere completo, compreso il protocollo. CrowdHandler supporta solo HTTPS. 
• ip - È l'indirizzo IP della richiesta dell'utente. Anche in questo caso, la provenienza di queste informazioni dipende dalla lingua e dal framework. L'IP è necessario. È usato per prevenire le frodi e individuare i bot.
• agent - è la stringa dell'agente utente. È anch'essa obbligatoria. Va recuperata dall'intestazione HTTP User-Agent.
• lang - È la lingua preferita dall'utente. È un parametro opzionale e può aiutare a identificare agenti fraudolenti. Si può ricavare dall'intestazione HTTP Accept-Language.

Se tutto va bene e l'URL fornito è protetto da una sala d'attesa, si dovrebbe 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
    }
}

Camminare attraverso l'uscita:

• token token è l'identificatore dell'utente. All'inizio non ne avevamo uno, quindi abbiamo fatto una richiesta POST, che non ne richiede uno, e questo significa che abbiamo ricevuto un nuovo token con il nostro primo risultato.
• promosso è l'attributo principale che ci interessa. Un valore di 0 significa che l'utente con questo token deve mettersi in coda per l'url specificato. Un valore di 1 significa che l'utente non ha bisogno di mettersi in coda. Questo token ha il valore promosso 0, che indica che l'utente deve mettersi 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 id univoco che identifica la risposta appena ricevuta. Potremmo utilizzarlo in seguito, per registrare le prestazioni di questa richiesta con l'API di CrowdHandler.
• Gli altri attributi sono interessanti e possono essere utili per la risoluzione dei problemi e il debug, ma non è necessario utilizzarli per una semplice integrazione. Se si è interessati a usarli per altri motivi, si può consultare il loro significato nella documentazione dell'API. 

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

Vedi qualcos'altro?

È possibile che non si ottenga la risposta del modello di cui sopra. Se la risposta è significativamente diversa, è possibile che si sia verificato uno dei seguenti errori, a seconda di ciò che si vede: 

• Un errore? Indica che c'è qualcosa di sbagliato nei parametri della richiesta. L'errore dovrebbe indicare cosa si sta facendo di sbagliato.
• Nessuna informazione sulla sala d'attesa? Se si inviano URL che non rientrano nell'ambito di nessuna sala d'attesa, si riceverà un token promosso con valore 1, ma non si otterranno informazioni sulla sala d'attesa. Si può provare a impostare una sala d'attesa di tipo catch-all, per facilitare i test.
• Nessun token? Se si prova a testare la chiamata utilizzando URL su nomi di dominio che non sono nemmeno registrati con il proprio account CrowdHandler, si riceverà comunque 1 come valore promosso (non siamo responsabili della protezione di quel dominio, quindi per quanto ci riguarda si è a posto!). Ma non riceverete un token. 
• Se si riceve lo stato 3, significa che il proprio IP è stato bloccato. Questo può accadere quando si effettuano molte richieste API pubbliche dallo stesso IP ed è comune quando si testa un'integrazione. Accedere al pannello di amministrazione, trovare il proprio IP (sotto domini > IP) e modificare lo stato del proprio IP in ignora. 

Ok, abbiamo fatto la prima chiamata, sappiamo qual è l'output e come dobbiamo reagire. Parleremo dei dettagli della gestione di queste informazioni dopo la prossima chiamata.

3. La seconda chiamata

GET /richieste/:token

Nel primo esempio non avevamo un token utente. La chiamata POST non riceve un token, ma ne restituisce uno. Quindi questa è la chiamata da fare quando l'utente sul sito non ha un token. Ma se l'utente è arrivato sul sito perché era in sala d'attesa e ce l'ha fatta, allora avrà un token. In questo caso, bisogna assicurarsi di utilizzarlo e conservarlo per controllarlo. Perché se gliene date uno nuovo, molto probabilmente finirà di nuovo in coda. 

Dove posso trovare il token?

Quando CrowdHandler reindirizza gli utenti al vostro sito, aggiunge il token all'URL. Viene inserito come parametro della stringa di query chiamato ch-id. Ad esempio https://yoursite.com/your-url?ch-id=tok_S0mET0k3n. È quindi necessario controllare il parametro dell'URL per trovare un token. Se lo si trova, si effettua la chiamata GET invece di quella POST.

Ma non è tutto!

L'utente continuerà a cliccare su molti altri link del vostro sito web. Per assicurarsi che l'utente non si ritrovi nella sala d'attesa, è necessario impostare un cookie di sessione ogni volta che si riceve il token e controllare il cookie ogni volta che non si trova il ch-id nell'URL. Se ancora non lo si trova, inviare la richiesta POST.

I token scadono?

Lo fanno. Ma ogni volta che si passa un token non valido, CrowdHandler lo ignora, tratta la richiesta come se non fosse stato impostato alcun token e invia un nuovo token oltre a verificare la richiesta. Questo significa che i token si puliscono da soli e non ci si deve preoccupare di tracciare e far scadere i token. Ma significa anche che il token che si riceve indietro non è necessariamente quello inviato. È necessario fidarsi del token ricevuto rispetto a quello inviato, quindi è necessario impostare il cookie ogni volta.

Devo controllare prima il cookie o il parametro URL?

Il parametro URL. In situazioni complesse, è possibile che l'utente abbia un nuovo token nella sala d'attesa, ma abbia ancora un vecchio cookie memorizzato nel sito. Se l'utente viene inviato dalla sala d'attesa, il nuovo token si troverà nell'URL, e si dovrà fare affidamento su questo token, piuttosto che su quello potenzialmente obsoleto impostato in precedenza come cookie. 

Naturalmente, non si deve usare l'assenza del parametro ch-id come un'istruzione per cancellare qualsiasi cookie esistente. Quindi controllate attentamente.

E poi... la chiamata:

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

La risposta è molto simile alla richiesta POST. Solo che questa volta possiamo vedere che il token ricevuto è lo stesso che abbiamo inviato. Le decisioni che la nostra integrazione deve prendere, sulla base di questi dati, sono esattamente le stesse della richiesta POST.

In conclusione

La chiamata POST e la chiamata GET restituiranno le stesse informazioni. Si effettua la chiamata POST quando non si è ricevuto un token dall'utente e si effettua la chiamata GET quando lo si è ricevuto. Queste chiamate non vengono effettuate in sequenza, ma sono alternative. In ogni caso, la risposta sarà nello stesso formato e l'azione da intraprendere sarà la stessa. 

È necessario memorizzare il token in un cookie o in un oggetto di sessione, in modo da poter convalidare l'utente più volte quando accede a diversi indirizzi del sito.

Prestate attenzione all'impostazione del cookie o della sessione del token, perché un utente in attesa potrebbe tentare di accedere ad altre pagine web del vostro sito e non volete dargli una nuova posizione in fondo alla coda. Per questo motivo:

1. Si consiglia di memorizzare il token alla prima occasione, senza aspettare di sapere se l'utente è in attesa o meno. 
2. Fate attenzione alla scadenza della sessione. L'applicazione potrebbe avere un archivio di sessione con un timeout di 20 minuti, ma l'utente potrebbe rimanere in sala d'attesa per ore. Un cookie di sessione che scade solo quando l'utente chiude il browser è una buona scelta. Un cookie permanente potrebbe essere ancora meglio. 

4. Quando effettuare la prima chiamata

Lo scopo di CrowdHandler è proteggere il sito da un carico eccessivo. Lo scopo del controllo di convalida è quello di garantire che l'utente del sito stia effettivamente accedendo a questo URL in questo momento. Pertanto, è necessario effettuare queste chiamate alla prima occasione possibile nel percorso di esecuzione del codice. Lo scopo è quello di risparmiare tempo e risorse di esecuzione del server. Non appena si conosce la richiesta dell'URL e si è in grado di effettuare la chiamata, bisogna farla.

5. Cosa fare con il risultato

• Se promosso è 1? uscire dal codice di controllo e tornare al flusso standard dell'applicazione. Servite l'URL come fareste normalmente.
• Se promosso è 0? allora reindirizzare l'utente alla sala d'attesa usando lo slug. Utilizzare un reindirizzamento HTTP 302 nel caso in cui l'"utente" sia un bot legittimo; questo indica al bot che il reindirizzamento dell'URL è temporaneo.
• Se si ottiene una risposta malformata o la chiamata all'API fallisce... CrowdHandler ha molti livelli di protezione, ma ci sono sono Sono molti i motivi per cui ciò potrebbe accadere e per cui è necessario reagire. Potrebbe verificarsi un problema di rete temporaneo nel vostro centro dati o su una dorsale Internet. Se il processo di chiamata API non va a buon fine, o il processo di analisi di un risultato legittimo non va a buon fine, o la valutazione del risultato non è stata effettuata. promosso fallisce, è necessario trattarlo come un'eccezione e gestirlo. Il modo in cui gestirla dipende da voi:
  • Il reindirizzamento in caso di fallimento presuppone che, se non si sa di più, l'utente debba essere messo in coda. Se si conosce lo slug della sala d'attesa standard (si potrebbe avere un catch-all predefinito con uno slug stabile), si potrebbe inviare l'utente lì. Se non lo si conosce, si può inviare un utente a https://wait.crowdhandler.comdove l'utente verrà servito con un modello generico, verrà interrogato regolarmente per ottenere informazioni migliori e verrà rimandato al vostro sito, o alla sala d'attesa appropriata, quando verrà ripristinato il normale servizio.
  • Fiducia in caso di fallimento: si può decidere di consentire all'utente di accedere alla pagina se la chiamata API fallisce. Ciò dipende dalla regolarità con cui il vostro sito registra un traffico elevato e dalla prevedibilità degli schemi. Se si è installato CrowdHandler solo per un uso occasionale e pianificato, con sale d'attesa specifiche per gli eventi, si può preferire di dare fiducia agli utenti nel caso in cui non si ricevano risposte ben formate dall'API di CrowdHandler.

6. Reindirizzamento di un utente

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

1. ch-id: il token restituito dall'API.
2. url: l'url richiesto dall'utente. Se i parametri delle query string sono importanti per voi (per ragioni di marketing/tracciamento o perché li utilizzate per gli ID dei prodotti e simili), dovete assicurarvi che siano passati come parte del parametro dell'url. 
3. ch-public-key: se non si conosce lo slug della sala d'attesa per i propri utenti, magari perché si è ricevuta una risposta malformata o nessuna risposta, è possibile inviare la propria chiave pubblica invece dello slug, utilizzando questo parametro. In questo modo la sala d'attesa della rete di sicurezza di CrowdHandler potrà utilizzare la chiave per cercare lo slug corretto e gestirlo in modo appropriato.

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

PUT /risposte/:id

La registrazione delle prestazioni della pagina consente a CrowdHandler di monitorare le prestazioni del dominio. Questo è utile quando si monitora il traffico intenso ed è fondamentale per abilitare la funzione di autotune.

Questa chiamata è una PUT e va a una nuova risorsa /responses/:id. L'ID è stato fornito come responseID nel risultato della prima chiamata effettuata.

Il payload di questa chiamata è simile a questo:

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

• è la risposta HTTP per la pagina che si sta servendo all'utente. In genere è 200, ma se si è in grado di catturare i codici di errore http è bene inviarli. Questo aiuterà CrowdHandler a identificare quando il sito web è in difficoltà*, consentendo all'autotune di intervenire. Se si omette questo parametro, CrowdHandler invierà per impostazione predefinita 200.
• tempo è il tempo di caricamento della pagina in millisecondi. Si può calcolare con:
  • a partire dal momento in cui si riceve la richiesta per la prima volta (a)
  • prendendo il tempo appena 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 sembri abbastanza semplice, è necessario prestare molta attenzione. Linguaggi e framework diversi hanno metodi diversi per tracciare il tempo in piccoli incrementi, possono esserci differenze o problemi di prestazioni a seconda che si utilizzino macchine virtuali o server bare-metal e diversi tipi di processore. Alcuni framework dispongono di API specifiche per il monitoraggio delle prestazioni delle pagine. Se si è sicuri, si può fornire a CrowdHandler una lettura molto accurata. Se 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 la successiva PUT. La stima del tempo di caricamento della pagina potrebbe essere influenzata dai tempi di rete e ha una risoluzione più bassa, ma l'informazione è sufficiente per un controllo dello stato di salute ed è migliore del valore estremamente impreciso che potrebbe essere fornito se si sbaglia il calcolo.

* Una risposta con un codice di errore viene gestita da CrowdHandler nello stesso modo in cui viene gestita una richiesta che supera il tempo massimo di risposta. Quindi, se gli errori 500 vengono serviti molto velocemente, ma la quantità di errori supera la soglia di accettabilità, l'autotune rallenterà il traffico come se le richieste rispondessero oltre la soglia di carico accettabile della pagina. 

Quando fare la telefonata.

Mentre la chiamata iniziale dovrebbe essere fatta il prima possibile, questa chiamata dovrebbe essere fatta il più tardi possibile, dopo che la pagina è stata servita all'utente. Inoltre, sembra ovvio, ma questa chiamata va fatta solo se si è effettivamente servito l'URL. Se si reindirizza l'utente alla sala d'attesa, si dovrebbe saltare del tutto questa chiamata. Quindi, dopo la prima chiamata, c'è un ramo condizionale tra l'invio del reindirizzamento o il servizio della pagina e la registrazione delle prestazioni.

8. Mettere tutto insieme

Il seguente pseudocodice** mette insieme tutto questo per descrivere un'integrazione semplice ma completa. Vedrete che rende l'idea in modo più rapido rispetto alle lunghe spiegazioni che abbiamo dato finora, ma comunque dovrete fare riferimento alle note per il contesto.

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 figlio illegittimo di ruby e python, due linguaggi leggibili, con API immaginarie e semplici per emettere chiamate API, recuperare i dati delle richieste e inviare le risposte. Speriamo che sia facile per voi leggere tra le righe.

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