L’API (interfaccia di programmazione delle applicazioni) consente ai clienti di integrare l’FMS con i loro sistemi, di prelevare e inviare dati su varie entità.
Il client effettua richieste HTTP al sistema, fornendo informazioni sull’azione prevista. I comandi HTTP vengono solitamente utilizzati in un’API:
- GET – Leggi la risorsa;
- POST – Cambia lo stato della risorsa;
Il contenuto richiesto è fornito in formato JSON con codifica UTF-8. Se viene utilizzato un altro formato, viene specificato nella descrizione del metodo.
Il codice di stato HTTP identifica lo stato della richiesta – per le richieste andate a buon fine, viene restituito il codice di stato 200. Insieme a questa risposta, verranno ricevute le informazioni richieste dal server. Le risposte variano a seconda del tipo di API utilizzata. Le risposte API per i diversi tipi di API sono descritte nelle sezioni successive.
Se si è verificato un errore nella richiesta inviata, il sistema restituirà un messaggio di risposta con un codice di stato. Codici di errore comuni:
- Codice 400 – Richiesta errata – La richiesta API non è stata riconosciuta.
- Codice 401 – Non autorizzato – Significa che le credenziali di autenticazione sono mancanti o non corrette;
- Codice 403 – Vietato – Significa che il client non ha il diritto di accedere alla risorsa richiesta o di eseguire l’azione richiesta;
- Codice 404 – Non trovato – Significa che la risorsa richiesta non è stata trovata.
- Codice 500 – Errore interno del server – contatta il supporto tecnico del tuo provider.
I codici di errore forniscono alcune informazioni generali sul tipo di errore, consentendo all’utente di identificare la radice del problema.
Alcune API hanno elementi opzionali (parametri) nella loro risposta; i parametri opzionali possono essere saltati dal sistema per vari motivi (assenza di dati, dati errati, tempo di risposta scaduto, ecc.) L’utente non deve dare per scontato che alcuni dati opzionali saranno sempre inclusi in una risposta.
Limitazioni API
Tutte le API hanno un’unica limitazione:
- Non più di 1000 richieste al minuto.
Questa limitazione è valida per tutte le API esistenti di FMS.
Autenticazione API
L’autenticazione e l’autorizzazione delle API sono necessarie per controllare l’utilizzo delle API da parte di diversi client e la loro integrazione con diversi sistemi. Per effettuare una richiesta autorizzata alle API del sistema, l’applicazione richiedente deve prima ottenere una API_key per conto dell’utente web del sistema.
I clienti possono ottenere una chiave API solo contattando direttamente il supporto tecnico dei loro fornitori di servizi. La chiave API è composta da lettere, numeri e simboli generati in modo casuale.
Esempio di richiesta che utilizza una API_key:
Se la chiave API_ è scaduta, rimossa o semplicemente disabilitata, il sistema restituirà la seguente risposta:
Gli endpoint API, i parametri di richiesta e le risposte possono essere visualizzati in anteprima in “Swagger” attraverso questo link: https://api.fm-track.com
Nota
È sempre necessario specificare una versione API in tutti i tipi di API.
Importante!
A causa del costante sviluppo sia dell’API che del sistema da cui richiede le informazioni, gli utenti possono talvolta ricevere parametri non elencati nelle descrizioni. Si raccomanda di ignorare semplicemente i parametri sconosciuti che non sono documentati nella descrizione di ciascuna API.
Versioni e compatibilità
La soluzione API viene costantemente aggiornata, migliorata e modificata in altro modo, pertanto è necessario capire cosa significa “Compatibilità” e come influisce sull’utente quando utilizza la soluzione API.
Quando un’API viene aggiornata, si verifica una delle due opzioni seguenti:
- L’API è retrocompatibile: ciò significa che le modifiche apportate non influenzeranno in alcun modo il flusso di lavoro dell’API, quindi non verrà creata una nuova versione.
- L’API non è retrocompatibile: ciò significa che alcuni componenti dell’API sono stati modificati e non funzionano più come prima. In questo caso, viene rilasciata una nuova versione dell’API.
Cosa si intende per versione API retrocompatibile:
- È stata aggiunta una nuova risorsa API;
- Sono stati aggiunti nuovi parametri di richiesta opzionali all’API esistente
- Sono state aggiunte nuove proprietà alle risposte API esistenti.
- L’ordine delle proprietà è stato modificato nelle risposte API esistenti.
- Modificare la lunghezza o il formato degli ID degli oggetti o di altre stringhe opache.
L’utente può tranquillamente supporre che gli ID degli oggetti generati dal sistema non superino mai i 255 caratteri, ma deve essere in grado di gestire ID con una lunghezza potenziale di 255 caratteri. Ad esempio, se l’utente utilizza MySQL, gli ID devono essere memorizzati in una colonna VARCHAR(255) COLLATE utf8_bin (la configurazione COLLATE garantisce la sensibilità alle maiuscole e minuscole nelle ricerche). - Aggiunta di nuovi tipi ENUM. – Il sistema deve gestire con grazia qualsiasi tipo di ENUM non conosciuto. Se ad esempio il tipo cambia da [Privato, Business] a [Privato, Lavoro, Business], il sistema non dovrebbe subire alcun effetto.