Iniziare con le API
Segui questa guida per accedere al portale, creare la tua applicazione, iscriverti alle API ed effettuare la tua prima chiamata.
1. Accedere al Portale API
I portali API di STEF ti consentono di iscriverti alle API STEF tramite applicazioni consumer personali oppure condivise all'interno di un team.
In qualità di dipendente STEF, non è necessario richiedere la creazione di un account per accedere ai portali.
Vai al portale desiderato e, al momento dell'autenticazione, fai clic sul pulsante Accedi come dipendente STEF.
Consulta la guida delle istanze APIM per ottenere l'elenco dei portali disponibili e dei relativi utilizzi.
Per poter creare un'applicazione consumer condivisa con il tuo team, è necessario richiedere la creazione di un team aprendo un ticket JIRA APIM e specificando il nome del team e il/i portale/i di destinazione.
2. Creare un'applicazione
Per poter consumare un'API, devi prima disporre di un'applicazione consumer. La sua creazione genera una credential, l'identificativo della tua applicazione durante una chiamata.
- Fai clic sul tuo profilo in alto a destra nel portale
- Fai clic sul pulsante Applications
- Fai clic sul pulsante New application
- Inserisci il nome e la descrizione della tua applicazione
- Per condividere questa applicazione con il tuo team, seleziona This is a team owned application e scegli il team desiderato
- Fai clic sul pulsante Create application
- Prendi nota della credential generata durante la creazione
3. Iscriversi a un'API
Un'applicazione consumer può iscriversi a una o più API in base alle proprie esigenze.
Usa il menu APIs per consultare il catalogo delle API STEF disponibili.
Vai ai prodotti che ti interessano per visualizzare la documentazione tecnica per sviluppatori, che presenta per ogni API:
- Le diverse operazioni supportate
- La definizione degli oggetti di input e output
- Esempi di codice per consumarle
Per iscriverti a un'API:
- Apri il dettaglio di un'API
- Fai clic su Use this API in alto a destra
- Fai clic sul pulsante Register associato all'applicazione che desideri iscrivere
L'iscrizione dovrà poi essere convalidata da STEF; per questo, contatta il tuo referente STEF IT.
Poiché un'applicazione può iscriversi a più API, ripeti la procedura di iscrizione per ciascuna API che desideri utilizzare.
Consultare e gestire le tue iscrizioni
Per consultare le iscrizioni di un'applicazione, fai clic sul tuo profilo in alto a sinistra e poi su Applications, quindi sul nome della tua applicazione. Nella scheda APIs, visualizzata automaticamente, troverai l'elenco delle tue iscrizioni e il relativo stato.
Puoi anche richiedere l'iscrizione ad altre API direttamente da questo menu, facendo clic su + API.
4. Consumare un'API
Tutte le invocazioni delle API STEF passano attraverso la Gateway API STEF per applicare le regole di sicurezza di accesso, garantire la protezione dei servizi backend del sistema informativo STEF e raccogliere statistiche di invocazione.
Le Gateway API sono accessibili tramite i seguenti URL:
- Produzione: https://api-suitelogi.stef.com
- Qualifica: https://api-suitelogi-qua.stef.com/
Per consumare un'API e rispettare le regole di sicurezza di accesso, aggiungi alla richiesta l'header HTTP X-STEF-Client-Id, valorizzato con la credential della tua applicazione consumer.
La documentazione tecnica per sviluppatori propone, per ogni API pubblicata sulla piattaforma, esempi di codice per invocare la Gateway API da diversi linguaggi: Shell, Python, Node.js, JavaScript, Go, Java, C# e Ruby.
Esempio di invocazione
curl -X GET "https://api.stef.com/v1/transport/orders" \
-H "X-STEF-Client-Id: <YOUR_APPLICATION_SECRET>" \
-H "Content-Type: application/json"
Oltre agli esempi di codice, la documentazione tecnica per sviluppatori propone moduli che consentono di invocare le API direttamente dal portale, in modalità interattiva, tramite il pulsante Try it!.