Linee guida Generali API TS-Digital
Header obbligatori ad ogni chiamata API
X-App-Name: id dell’applicativo (es: TS500, TS010, ecc). Non utilizzare valori diversi dall’appname assegnato in quanto verranno introdotti controlli che bloccheranno tutte le chiamate con AppName non censiti
X-App-Version: versione dell’applicativo, utile per determinare eventuali problemi su una particolare versione, statistiche di utilizzo, ecc
X-Request-ID: Identificativo univoco di una singola richiesta. (es. cjqqbbezk139w08878awoj1p0 generato con la libreria https://github.com/ericelliott/cuid). Utile per determinare eventuali problemi su una particolare chiamata, eventualmente associata al log dell’applicativo stesso.
X-Correlation-ID: Identificativo correlatore di tanti X-Request-ID. Il raggruppamento è deciso dal chiamante in quello che può essere definita una singola attività (es. Il provisioning di una azienda può essere formato da 3 chiamate, creazione azienda, creazione connessione, creazione servizio, sono 3 X-Request-ID differenti ma correlati dallo stesso ID in quanto per l’applicativo l’azione può essere vista come atomica)
X-Item-ID: itemID (vedi sopra ItemID) soggetto dell’attuale azione. Nelle installazioni enterprise può coincidere con l’itemID del licenziatario, nel caso di studi può essere l’itemID su cui il professionista sta lavorando. Utile per determinare eventuali problemi su un particolare cliente, statistiche di utilizzo, ecc.
X-User-ID: identificativo della chiave tecnica dell’applicativo utilizzata per ottenere il token dalle API di auth (es: b7b0ce7b-86a1-4298-9da7-82522fc28a09, ecc). Insieme all’AppName verrà utilizzato per identificare puntualmente la o le installazioni in caso di problemi, ma anche statistiche di utilizzo, ecc..
X-Manager-ID: opzionale per i prodotti che non prevedono l’operatività su itemID terzi. Nel caso di studi invece è l’itemID del professionista (quindi potrebbe coincidere con l’itemID del licenziatario ad es.) che sta operando per conto dell’X-Item-ID. Utile per determinare eventuali problemi su un particolare cliente, statistiche di utilizzo, ecc.
Errori durante le chiamate
Prestare attenzione agli stati http delle risposte e agire di conseguenza (https://httpstatuses.com/)
Esempio: se ottengo un 400 Bad Request è inutile riprovare la richiesta perchè otterrò sempre lo stesso risultato. Confrontiamoci per capire le logiche di business in caso di dubbi (no confirmDownload su flussi attivi, dati obbligatori in upload, ecc)
A breve verranno introdotti limiti/controlli sul numero di chiamate effettuabili in un arco temporale (da definire). In caso di sforamento dei tali limiti è necessario gestire il codice http 429 Too many Requests.