Vai al contenuto principale

Integrazione delle API in SMARTFENSE

  • Aggiornato

Questo articolo spiega cos'è una API, come funziona all'interno di SMARTFENSE e come registrare una nuova applicazione per interagire in modo sicuro con la API di SMARTFENSE.

 

Cos'è un'API?

Definizione generale

Un'API (Interfaccia di Programmazione delle Applicazioni) è un insieme di protocolli e strumenti che permettono a diverse applicazioni software di comunicare tra loro.
Agisce come un intermediario che consente a un programma di accedere ai dati e alle funzioni di un altro, senza la necessità di conoscerne il funzionamento interno.

In altre parole, un'API offre un modo sicuro e standardizzato di scambiare informazioni tra sistemi.

 

Applicazioni registrate

Ogni richiesta effettuata alla API di SMARTFENSE deve essere autenticata tramite le credenziali di un'applicazione registrata.

Nella sezione Configurazione > Integrazioni > API, potrai registrare le API necessarie con i dati della tua organizzazione.
 

Per mantenere la sicurezza dell'integrazione:

  • Tutte le richieste devono essere effettuate utilizzando HTTPS.
  • È obbligatorio includere le credenziali dell'applicazione nell'intestazione di autenticazione di ogni richiesta.

 

Registrare una nuova applicazione

  1. Nome: consente di assegnare un nome descrittivo all'applicazione. Questo ne facilita l'identificazione quando si gestiscono più integrazioni.
  2. Client id (campo di sola lettura): identificatore unico assegnato all'applicazione. Viene utilizzato durante il processo di autenticazione e autorizzazione per riconoscere la fonte della richiesta.

  3. Client secret (campo di sola lettura): chiave privata e unica che autentica l'applicazione.
     

    Nota: questo valore viene mostrato solo una volta al momento della creazione dell'applicazione. Non può essere recuperato successivamente. Salvalo in un luogo sicuro.

     

  4. Tipo di client: specifica come verrà utilizzato il client secret:
    • Confidenziale: per l'uso nel backend di un server, dove le credenziali sono protette.
    • Pubblico: per l'uso lato client; viene creato tramite un metodo di cifratura più robusto.
  5. Tipo di concessione di autorizzazione: definisce il flusso di autenticazione utilizzato per ottenere un token di accesso.
     
    • Authorization code: flusso più sicuro e comune, raccomandato per applicazioni con server backend.
    • Client Credentials: adatto per comunicazione tra server o servizi senza intervento degli utenti finali.
  6. URI di reindirizzamento: consente di inserire uno o più URL separati da virgola. Una volta completato il flusso di autenticazione, il sistema reindirizza a uno degli indirizzi inseriti.
  7. Ambiti (Scopes): definiscono i permessi specifici di cui l'applicazione ha bisogno per interagire con l'API.
    Per sicurezza, seleziona solo gli ambiti minimi richiesti. Come specificato nella documentazione dell'API da cui vogliamo ottenere dati.
    Puoi consultare i permessi disponibili nella sezione Authorizations di ogni endpoint all'interno della documentazione ufficiale della API di SMARTFENSE.
  8. Una volta completati tutti i campi, clicca su Salva per registrare l'applicazione.



Documentazione ufficiale dell'API di SMARTFENSE

SMARTFENSE mette a disposizione la documentazione ufficiale della sua API, dove è possibile consultare tutti gli endpoint disponibili, i relativi parametri e i formati di risposta.

Come accedere alla documentazione

  1. Acceda a Configurazione > Integrazioni > API.
  2. Faccia clic sul link API di SMARTFENSE (si raccomanda di aprirlo in una nuova scheda).
  3. Verrà reindirizzato all'URL pubblico della documentazione, con il seguente formato: https://nometenant.takesecurity.com/api/schema/redoc/ Dove nometenant corrisponde al nome della sua istanza.

Informazioni disponibili nella documentazione

La documentazione è organizzata in un menu laterale con le seguenti sezioni generali:

  • Introduzione: presentazione dell'API e dei principi su cui è costruita (REST, verbi HTTP, codici di risposta standard).
  • URL Base: indica l'URL base su cui si costruiscono tutti i percorsi degli endpoint. Tutti i percorsi documentati sono relativi a questo URL.
  • Autenticazione: spiega i flussi di autenticazione supportati (OAuth 2.0 Client Credentials e Authorization Code), come ottenere le credenziali e come includere il bearer token nell'intestazione Authorization di ciascuna richiesta.
  • Extra: informazioni complementari utili per gli integratori.

Inoltre, la documentazione include sezioni per risorsa, in cui sono raggruppati gli endpoint correlati. Le sezioni disponibili sono:

  • Campagne
  • Utenti
  • Gruppi
  • Audit
  • Organizzazione
  • Contenuti
  • Gamification

Informazioni contenute in ciascun endpoint

Accedendo al dettaglio di un endpoint, troverà le seguenti informazioni organizzate in una vista a due colonne:

Colonna sinistra — definizione dell'endpoint

  1. Metodo HTTP e percorso: ad esempio, GET /api/v1/campaigns.
  2. Descrizione: spiega quali informazioni consente di ottenere o quale azione esegue l'endpoint.
  3. Authorizations: indica lo schema di autorizzazione richiesto (ad esempio, oauth2) e gli scope necessari.
  4. Query parameters: elenco dei parametri ammessi dalla richiesta. Per ciascun parametro viene indicato:
    • Nome del parametro.
    • Tipo di dato (string, integer, ecc.).
    • Descrizione della sua utilità.
    • Formato previsto, se applicabile (ad esempio, date nel formato YYYY-MM-DD hh:mm:ss in GMT).
    • Valori possibili, quando il parametro è limitato a un insieme (ad esempio, i componenti ammessi: trainings, exams, surveys, videos, videogames, phishing, ransomware, smishing, newsletters, liveSimulations, webGroup).
    • Valore predefinito e valore massimo, quando applicabile (ad esempio, page = 1, page_size = 100, massimo 100).
  5. Responses: dettaglia i codici di risposta possibili e, per ognuno, lo schema previsto:
    • 200: risposta corretta, con il dettaglio dei campi restituiti (ad esempio, count, next, previous e l'array della risorsa richiesta).
    • 400 e altri codici di errore: includono il campo error con il messaggio corrispondente.

Colonna destra — esempi

  1. Request samples: esempio della richiesta in diversi linguaggi, di solito cURL e Python, incluse le intestazioni e il bearer token.
  2. Response samples: esempio del corpo della risposta per ciascun codice di stato documentato, in formato application/json.

💡 Migliori pratiche

  • Utilizzi sempre HTTPS nelle richieste all'API per proteggere i dati trasmessi.
  • Conservi il Client secret in un repository sicuro, poiché non potrà visualizzarlo nuovamente.
  • Selezioni il flusso di autenticazione (Authorization code o Client Credentials) in base al tipo di integrazione e al livello di sicurezza richiesto.
  • Limiti gli scope al minimo necessario per ridurre i rischi di esposizione.
  • Apra la documentazione ufficiale in una nuova scheda per mantenere disponibile la schermata di configurazione durante la consultazione degli endpoint.
  • Prima di implementare un'integrazione, verifichi nella documentazione i parametri ammessi, i valori possibili e i limiti di ciascun endpoint (ad esempio, page_size massimo) per progettare query efficienti.
  • Controlli nella sezione Authorizations di ciascun endpoint gli scope esatti da assegnare all'applicazione registrata.

Correlato a

Articoli correlati