Autenticazione

L'accesso alle API avviene tramite autenticazione basata su Bearer Token.

Il token viene generato a partire da uno user e una password specifica per singola installazione. Una volta creata la credenziale, lo user non è più modificabile. Inoltre, la password è autogenerata e rimane visibile solo in fase di creazione; è comunque possibile richiedere un cambio password in qualunque momento, ma non sarà mai possibile, per l'assistenza Sistemi / Peoplelink recuperarla o visualizzarla in un secondo momento.

È possibile richiedere più utenze, per finalità diverse e con limitazioni differenti. Il token, di default, ha una validità di dieci minuti.

Il token deve essere inviato in ogni richiesta HTTP tramite header Authorization. Le richieste prive di token, con token non valido o con token scaduto verranno rifiutate dal sistema con un errore di autenticazione.

A corredo dell'header Authorization sarà obbligatorio indicare anche l'header X-PL-ApiToken, fornito anch'esso in fase di approvazione della richiesta di accesso.

Al contrario del Bearer Token, quest'ultimo header non ha scadenza.

Il sistema prevede l'utilizzo di due chiavi API distinte:

·         chiave per endpoint in lettura, denominata UniversaRead

·         chiave per endpoint in scrittura, denominata UniversaWrite.

Questa separazione permette di applicare un livello aggiuntivo di sicurezza e controllo sugli accessi. Gli endpoint in lettura sono generalmente utilizzati per recuperare dati dal sistema. Gli endpoint in scrittura sono utilizzati per creare, modificare o, in determinati casi, eliminare dati.

IP whitelist

Per ottimizzare il livello di sicurezza, l'accesso alle API può essere protetto anche tramite IP whitelist. Questo significa che le chiamate API sono consentite solo se provenienti da indirizzi IP preventivamente autorizzati.

Durante la richiesta di attivazione delle credenziali, il cliente o partner può comunicare gli indirizzi IP pubblici, sia essi singoli IP o range di indirizzi, sia IPv4 sia IPv6, dai quali verranno effettuate le chiamate. Se non verranno indicate limitazioni agli IP, le API saleranno questo layer di controllo. In caso contrario, le richieste provenienti da IP non presenti in whitelist verranno bloccate.

In caso di modifica dell'infrastruttura del cliente o partner, ad esempio cambio IP, nuova sede, nuovo server o nuovo ambiente cloud, sarà necessario richiedere l'aggiornamento della whitelist, senza l'obbligatorietà di cambiare o creare una nuova utenza di accesso.

Abilitazione degli endpoint

Ogni utenza API può essere configurata per accedere solo a determinati endpoint. Questo consente di limitare l'utilizzo delle API alle sole funzionalità necessarie per l'integrazione del cliente o partner.

La lista degli endpoint è recuperabile direttamente dallo swagger all'indirizzo https://webapi.peoplelinkonline.com/Swagger.

Di default, salvo indicazioni specifiche, tutti gli endpoint disponibili saranno abilitati. Nel caso in cui il cliente o partner abbia necessità di accedere solo a un sottoinsieme di API, tale informazione deve essere comunicata in fase di richiesta credenziali o successivamente tramite richiesta di ri-configurazione. L'aggiornamento della lista degli endpoint non comporta la necessità di cambiare o creare una nuova utenza di accesso.

Rate limit

Le API sono soggette a rate limit.

Il rate limit è un meccanismo che limita il numero massimo di richieste che un client può effettuare in un determinato intervallo di tempo. Questo sistema serve a:

·         garantire la stabilità del servizio

·         prevenire utilizzi anomali o eccessivi

·         proteggere l'infrastruttura da sovraccarichi

·         assicurare un utilizzo equo delle risorse tra tutti i clienti e partner.

Quando il limite viene superato, il sistema può restituire un errore HTTP 429 - Too Many Requests. A corredo, la response includerà alcuni header HTTP utili a conoscere lo stato corrente del rate limit, ovvero:

·         X-RateLimit-Limit: numero massimo di richieste consentite nella finestra temporale corrente

·         X-RateLimit-Remaining: numero di richieste ancora disponibili nella finestra temporale corrente

·         Retry-After: tempo, in secondi, da attendere prima di effettuare una nuova richiesta, normalmente presente in caso di errore 429.

Il client che utilizza le API deve gestire correttamente il rate limit, evitando di continuare a inviare richieste quando il limite è stato raggiunto.

In particolare, è consigliato:

·         leggere gli header di rate limit restituiti dal server

·         rallentare automaticamente l'invio delle richieste quando X-RateLimit-Remaining è basso

·         sospendere temporaneamente le chiamate in caso di risposta 429

·         rispettare il valore indicato da Retry-After, se presente

·         implementare meccanismi di retry controllato

·         evitare retry immediati e continui

·         utilizzare una strategia di backoff progressivo in caso di errori ripetuti.

Il rate limit impostato di default sulle API è di 20 chiamate al minuto per ogni end-point. È possibile richiedere una modifica di tale valore tramite lo stesso caso AOL o con un caso ad-hoc, indicando il tipo di esigenza, l'end-point coinvolto e il volume previsto di chiamate.

Sicurezza e gestione delle credenziali

Le credenziali API devono essere conservate in modo sicuro.

È responsabilità del cliente o partner evitare la condivisione non autorizzata di:

·         Bearer Token

·         X-PL-ApiToken

·         eventuali credenziali o informazioni tecniche/riservate associate all'utenza.

Le chiavi non devono essere inserite direttamente nel codice sorgente, soprattutto se versionato in repository condivisi.

È consigliato utilizzare sistemi sicuri di gestione dei segreti, come:

·         variabili d'ambiente

·         secret manager

·         vault aziendali

·         configurazioni cifrate.

In caso di sospetta compromissione delle credenziali, è necessario richiederne immediatamente la revoca e la rigenerazione. Inoltre, l'accesso alle API può essere revocato o limitato in caso di:

·         utilizzo non conforme

·         superamento ripetuto dei limiti consentiti

·         tentativi di accesso non autorizzati

·         utilizzo da IP non autorizzati

·         compromissione delle credenziali

·         violazione degli accordi contrattuali o tecnici.

Eventuali modifiche alla configurazione dell'utenza API, come aggiornamento IP, rigenerazione chiavi o abilitazione/disabilitazione endpoint, devono essere richieste tramite i canali di supporto previsti.

Scadenza delle credenziali

Le credenziali di accesso alle API possono essere soggette ad una data di scadenza.

La scadenza dell'utenza è definita manualmente, con indicazione di una data assoluta (es.: il 31/12/2027), e definisce il termine entro il quale le credenziali API risultano valide e utilizzabili per l'accesso agli endpoint autorizzati.

Quando un'utenza API si avvicina alla data di scadenza, il sistema segnala tale informazione tramite l'header HTTP di risposta Sunset. L'header Sunset viene valorizzato solo quando il tempo residuo alla scadenza effettiva è compreso nei 90 giorni precedenti la data di scadenza.

Fino alla data indicata nell'header, l'utenza può continuare a utilizzare le API, salvo eventuali revoche, limitazioni o sospensioni. Successivamente alla scadenza, le chiamate effettuate con tale utenza saranno considerate non valide e verranno rifiutate dal sistema.

La presenza dell'header Sunset non indica un errore nella chiamata, ma rappresenta un'informazione preventiva sulla futura scadenza dell'utenza API. L'assenza dell'header Sunset indica che, al momento della chiamata, l'utenza non si trova nella finestra di preavviso dei 90 giorni precedenti la scadenza oppure che non è prevista una scadenza configurata.

Logging delle chiamate API

Tutte le chiamate effettuate verso le API possono essere registrate dal sistema a fini di sicurezza, monitoraggio, audit e supporto tecnico. Il logging delle chiamate consente di tracciare l'utilizzo delle API e di verificare eventuali anomalie, errori applicativi, superamenti dei limiti di utilizzo o tentativi di accesso non autorizzati.

Le informazioni registrate possono includere, a titolo esemplificativo:

·         Data e ora della richiesta

·         Endpoint invocato

·         Metodo http

·         Indirizzo IP sorgente

·         Esito della chiamata

·         Codice HTTP restituito

·         Headers

·         Tempo di esecuzione

·         Eventuali indicazioni tecniche in caso di errori o eccezioni verificatesi in fase di chiamata agli endpoint.

Le API, acronimo di Application Programming Interface, sono interfacce software che permettono a sistemi diversi di comunicare tra loro in modo standardizzato.

Attraverso le API, clienti, Partner o sistemi esterni possono integrare le funzionalità del software PEOPLELINK all'interno delle proprie applicazioni, automatizzare processi, leggere dati, inviare informazioni o sincronizzare contenuti tra piattaforme differenti.

Le API esposte dal sistema sono progettate per consentire un'integrazione sicura, controllata e tracciabile, nel rispetto delle policy di autenticazione, autorizzazione, sicurezza e limiti di utilizzo definiti dal servizio.

La specifica tecnica completa degli endpoint disponibili è consultabile pubblicamente all'indirizzo https://webapi.peoplelinkonline.com/Swagger tramite documentazione Swagger / OpenAPI, che descrive nel dettaglio:

·         endpoint disponibili

·         metodi HTTP supportati

·         parametri richiesti e opzionali

·         struttura delle request

·         struttura delle response

·         codici di errore

·         snippet di esempio, per l'implementazione delle chiamate in vari linguaggi di programmazione.

La documentazione Swagger rappresenta il riferimento tecnico ufficiale per l'utilizzo delle API. Non saranno forniti PDF o materiale cartaceo/digitale differente dall'URL dello swagger, anche se richiesta del cliente o del Partner.

Nel linguaggio comune, il termine Swagger indica la pagina di documentazione tecnica attraverso cui consultare le API. Più precisamente, OpenAPI è il formato che descrive le API, mentre Swagger UI è l'interfaccia che rende quella descrizione navigabile. Swagger UI è predisposto anche per effettuare chiamate di prova agli endpoint, ma quest'ultima opzione non è attiva su PEOPLELINK.

Swagger permette quindi di capire come costruire una richiesta, quali informazioni inviare e quale risposta aspettarsi.

Orientarsi nell'interfaccia

L'interfaccia dello Swagger PEOPLELINK mette a disposizione due definizioni, selezionabili dal menu Select a definition posto in testata:

·         quella del servizio token ACS, dedicata all'autenticazione e all'ottenimento del token di accesso temporaneo

·         quella delle API applicative, che documenta le funzionalità disponibili per l'integrazione, con i relativi parametri, formati delle richieste e risposte previste.

Il primo passo è quindi scegliere la definizione corrispondente all'attività da svolgere: ottenere il token oppure consultare e utilizzare le API vere e proprie.

Nella sezione Servers sono indicati gli indirizzi dei due ambienti disponibili: produzione, destinato all'utilizzo operativo, e sviluppo, da utilizzare per le attività di sviluppo e test se si dispone di un ambiente di sviluppo dedicato.

È importante distinguere queste due selezioni: la definizione determina quale documentazione viene visualizzata, mentre il server mostra la destinazione che le chiamate dovranno avere. Prima di procedere, occorre verificare di aver scelto l'ambiente corretto e di utilizzare indirizzi e credenziali coerenti per il servizio ACS e per le API applicative, tenendo presente che i rispettivi URL sono distinti.

Scoprire come sono organizzate le API

Gli endpoint delle API sono categorizzati sulla base del modulo PEOPLELINK oppure, nel caso siano generali, ovvero validi per tutti i moduli, indicate come ALL. Sono anche categorizzati in base al fatto che siano in lettura o in scrittura (evidenziazione in rosso). Questa organizzazione permette di individuare l'area interessata senza dover esaminare subito tutti i percorsi disponibili. In sequenza, in ogni categoria, sono elencati tutti gli endpoint a quest'ultima associati (evidenziati in blu).

Nello Swagger PEOPLELINK, i metodi HTTP, indicati alla sinistra di ogni endpoint, non indicano che un determinato endpoint sia in scrittura (POST) o in lettura (GET). Non devono, quindi, essere interpretati secondo una corrispondenza RESTful/CRUD.

La regola pratica è: il metodo indica come inviare la richiesta; la documentazione indica che cosa farà il servizio.

Ogni riga di ogni endpoint ha una struttura così composta:

1.      metodo HTTP (GET o POST)

2.      path dell'endpoint, da concatenare con l'URL del server

3.      argomento e dati trattati dall'endpoint

4.      icona per copiare l'endpoint (a comparsa quando il mouse viene posizionato sopra uno specifico endpoint)

5.      icona per aprire tutti i dettagli dell'endpoint

Inoltre, dopo ogni nuovo rilascio in produzione, verrà aggiunto un badge grafico per indicare gli endpoint nuovi (NEW) o quelli che hanno subito una modifica (UPDATED). Sono previsti anche due badge speciali il cui scopo è indicare se l'endpoint è in beta (BETA) o in anteprima (PREVIEW).

Comprendere una scheda di dettaglio di un endpoint

Quando apri il dettaglio di un endpoint (clic sulla rispettiva riga), vengono mostrate tutte le informazioni necessarie al suo utilizzo, come spiegazione estesa, URL di destinazione, dati della request, formati, dati della response, snippet di codice, ecc.

Parametri e corpo della richiesta

I Parameters, presenti sia negli endpoint in GET che in POST, possono essere collocati nel path dell'URL, nella query string o negli header. La posizione è significativa: un valore documentato come parametro di header non va spostato arbitrariamente nel corpo della richiesta o in query string. Per ciascun parametro sono indicati il nome, il tipo, l'eventuale formato, l'indicazione di obbligatorietà, la posizione, una descrizione funzionale, eventuali valori di esempio, di default o consigliati.

Tutti gli endpoint PEOPLELINK richiedono sempre 4 parametri:

·         X-PL-ApiToken: APIKey per gli endpoint in lettura o in scrittura, generato su PEOPLELINK nella funzionalità Chiavi di accesso per le API

·         User-Agent: nome identificativo della procedura che sta eseguendo la chiamata; altamente consigliato utilizzare una nomenclatura del tipo NomeAzienda/NomeApplicativo 1.0 dove:

o   NomeAzienda indica la ragione sociale del cliente (senza spazi e senza caratteri diversi da A-Z e 0.9)

o   NomeApplicativo indica un nome di riferimento dell'applicativo o della procedura che sta utilizzando le API

o   1.0 indica la versione dell'applicativo

·         Accept-Language: Culture, tra quelle supportate da PEOPLELINK, da utilizzare per nelle response. Il default è it-IT

·         Accept-Encoding: indica l'encoding da utilizzare nella risposta; altamente consigliato impostarlo su gzip per ridurre la dimensione dei dati scambiati.

Altri parametri possono essere richiesti in base alle necessità dell'endpoint, principalmente per gli endpoint in GET.

Il Request body, presente negli endpoint di tipo POST, descrive invece il contenuto da inviare nel corpo della richiesta. Il tipo di contenuto, come application/json oppure application/x-www-form-urlencoded, fa parte del contratto dell'API: non è una preferenza liberamente sostituibile dal client. Il body può essere composto da uno o più elementi e nello schema vengono indicati, per ognuno, il nome, il tipo l'eventuale formato, l'indicazione di obbligatorietà, una descrizione funzionale, eventuali valori di esempio, di default o consigliati.

La sezione Example value, disposta alla sinistra dello Schema, aiuta a capire la forma dei dati, ma non va copiato senza sostituire i valori dimostrativi e verificare i requisiti. Per distinguere campi obbligatori, valori ammessi e formati, usa lo schema e le descrizioni, non soltanto l'esempio visualizzato.

Risposte e interpretazione degli errori e dei warning

La sezione Responses documenta le risposte previste per l'operazione selezionata, indicando gli stati HTTP, le relative descrizioni, la struttura del corpo della risposta ed eventuali header. Queste informazioni descrivono il comportamento atteso dell'API e non rappresentano la risposta effettivamente ricevuta durante un test.

La colonna Code elenca gli stati HTTP documentati. Per le API PEOPLELINK, tali stati devono essere interpretati come segue:

·         200: restituito sia se la risposta è valida sia se vengono riscontrati errori; Lo stato HTTP 200, da solo, non garantisce quindi il successo dell'operazione. In questo caso, il campo statusCode presente nel corpo della risposta indica l'esito applicativo:

o   200: Esito positivo

o   400: Con errori

·         401: token mancante o non valido. Il corpo della risposta è da ignorare

·         429: troppe richieste inviate in un breve lasso di tempo. Limite di frequenza superato

·         500: errore interno del server. Il corpo della risposta è da ignorare

·         Eventuali altri stati HTTP non documentati vanno sempre trattati come errori generali.

La colonna Description riporta la spiegazione dello stato HTTP e la documentazione del contenuto associato. Comprende lo schema della risposta, con la struttura delle proprietà, i nomi dei campi, i tipi di dato, i formati e le descrizioni funzionali. Quando previsti, oltre al corpo della risposta, alcune operazioni delle API PEOPLELINK possono restituire specifici header HTTP contenenti informazioni utili per la gestione dell'integrazione. Gli header non devono essere interpretati come parte del JSON restituito dall'API: appartengono alla risposta HTTP e devono quindi essere letti separatamente dal client. La loro presenza dipende dallo stato HTTP restituito e dalla condizione che si è verificata. Le API PEOPLELINK possono restituire i seguenti Header in response:

·         Warning: segnala la deprecazione del token e informa di pianificarne la sostituzione

·         Sunset: indica che sull'utenza è stata indicata una scadenza e che è necessario pianificare il rinnovo delle credenziali prima della data indicata

·         X-RateLimit-Limit: indica il limite massimo di chiamate consentite alle API in un determinato lasso di tempo

·         X-RateLimit-Remaining: indica il numero di richieste alle API ancora disponibili prima di raggiungerne il massimo in un determinato lasso di tempo

·         Retry-After: indica il numero di secondi da attendere prima che il rate limit si azzeri.

La colonna Links non è rilevante ai fini dell'integrazione e può essere ignorata.

Gli snippet di codice

Gli snippet sono frammenti di codice che mostrano come costruire una chiamata. Servono a passare dalla descrizione dell'API a una possibile implementazione nel proprio ambiente di sviluppo.

Lo Swagger PEOPLELINK mette a disposizione, su ogni endpoint, una sezione denominata Code snippets, con una serie di opzioni standard tra applicativi e linguaggi di programmazione. Al clic sul pulsante specifico, viene mostrato il rispettivo codice di esempio, con destinazione e metodo compilati sulla base del server selezionato, segnaposti e dei dati di esempio per gli Header, le QueryString, il Path e/o il Body. Gli snippet gestiti dallo swagger PEOPLELINK sono:

·         Postman

·         cURL

·         C# (HttpClient)

·         Python

·         Kotlin

·         Javascript (fetch)

·         Javascript (jQuery)

Considera lo snippet come un punto di partenza, non come un'integrazione pronta per la produzione. Nel codice applicativo prevedi anche la corretta gestione delle rate limit, timeout, controllo degli errori e protezione dei segreti. Verifica, quindi, che quella rappresentazione contenga i valori desiderati.