API per gli sviluppatori
Grazie alle API di My Wi-Fi Service gli sviluppatori possono interfacciare le loro applicazioni/siti Web con i servizi offerti dalla nostra piattaforma. Le API possono essere utilizzate ad esempio per ottenere la lista degli utenti, l'elenco dei gruppi, dei piani tariffare, per aggiungere, cancellare o modificare gli utenti e molto altro.
Elenco completo delle API disponibili
Tecnologie utilizzate
Per quanto riguardo l'autenticazione viene utilizzato il protocollo OAuth 2
con la modalità 3-legged OAuth, mentre le chiamate ai servizi avvengono in modalità REST.
Lo scambio di dati da e verso i servizi esposti avviene utilizzando i formati Json e XML ed il set di caratteri utf-8.
Formato dei dati
- Valuta : viene usato il simbolo "." per separare i decimali. Esempio di formati validi sono i seguenti : 10.5 , 0.5 , 35.0 , 35
- Data e ora : le api utilizzano il formato ISO 8601. Le date UTC sono scritte con la Z finale.
Esempi :
2012-07-27T18:51:45.53403Z // UTC
2012-07-27T11:51:45.53403-07:00 // Locale
Registrazione dell'applicazione da realizzare
Per utilizzare i servizi lo sviluppatore dovrà effettuare una registrazione inviando una mail all'indirizzo info@softvision.it con i seguenti dati :
- Nome e cognome / azienda.
- Login utilizzato per accedere all'applicativo My Wi-Fi Service.
Utilizzo delle API
Vediamo ora più in dettaglio come utilizzare le API di My Wi-Fi Service.
Il vostro applicativo dovrà innanzitutto ottenere un Token (stringa alfanumerica) dal nostro server. Questo Token, la cui validità è di 24 ore,
dovrà essere poi inserito in ogni successiva richiesta di chiamata alle API.
Per ottenere il Token è necessario effettuare una chiamata al nostro server utilizzando il protocollo OAuth2.
I parametri di cui avrete bisogno sono i seguenti :
- client_id e client_sectret (forniti dalla Softvision dopo la registrazione dell'applicativo)
- Authorization end point : https://app.mywifiservice.com/OAuth/Authorize
- Token end point : https://app.mywifiservice.com/OAuth/Token
- Scope : rappresenta i privilegi richiesti dall'applicativo. Può assumere i valori 'READ', 'WRITE' o 'READ WRITE'
- Return url : è la url a cui si viene reindirizzati dopo la richiesta di inserimento delle vostre credenziali di accesso. Generalmente coincide con la pagina principale del vostro applicativo/sito web.
Il flusso dello operazioni è a grandi linee il seguente :
1) L'applicativo effettua una chiamata all'Authorization end point. All'utente viene richiesto di inserire le proprie credenziali di accesso del suo account My Wi-Fi Service.
Al termine dell'operazioni si viene reindirizzati all'url di ritorno del vostro applicativo.
2) L'applicativo richiede il Token con una chiamata al Token end point.
3) L'applicativo riceve il Token ed il Refresh Token. Il primo può essere utilizzato per 24 ore al termine delle quali è possibile ripetere
le procedure 1) e 2) per ottenere un nuovo Token oppure è possibile utilizzare il Refresh Token per rinnovare la scadenza del Token originale.
Una volta ottenuto il Token possiamo effettuare le chiamate alle API effettuando delle richieste REST all'indirizzo api.mywifiservice.com.
Vediamo ad esempio una chiamata per ottenere la lista dei clienti del nostro account My Wi-Fi Service.
Richiesta
GET https://api.mywifiservice.com/v1/registeredusers HTTP/1.1
Accept: application/json
Content-type: application/json
Accept-Charset: UTF-8
Authorization: Bearer TOKEN
Risposta
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Content-Length: 753
Date: Sat, 28 Apr 2012 13:19:40 GMT
[{"RegisteredUserID":14646,"FirstName":"Mirko","LastName":"De Santis","Login":"343412434","Password":"afr454tgfgf","GroupID":3,"StateInfo":196,"WeeklyRatePlanID":3,
"Address":"","City":"Roma","Province":"","ZIPCode":"67051","DocumentIssuedBy":null,"BornDate":"2012-03-02T00:00:00","RegistrationDate":null,
"DocumentIssuedDate":"2012-03-02T00:00:00","DocumentNumber":null,"Telephone":"3444442423","EMail":"","MobilePhone":null,"Note":null,"DocumentTypeID":-1,
"Balance":5.6895,"UserType":0,"IsoCountryCode":"IT","NavigationModeCode":1,"MacAddress":"AC-08-E0-DE-F2-C7",
"RegisteredBySMS":false,"Disabled":false,"Sold":false,"AccountWithExpiration":false,"AccountExpiration":null,"TicketExpirationDate":null},
{"RegisteredUserID":14649,"FirstName":"1 ora","LastName":null,"Login":"104032500","Password":"8795462A791E0D9BE95D966ED69354AA","GroupID":3,
"StateInfo":208,"WeeklyRatePlanID":3,"Address":null,"City":null,"Province":null,"ZIPCode":null,"DocumentIssuedBy":null,
"BornDate":null,"RegistrationDate":null,"DocumentIssuedDate":null,"DocumentNumber":null,"Telephone":null,"EMail":null,"MobilePhone":null,
"Note":null,"DocumentTypeID":null,"Balance":0.0000,"UserType":1,"IsoCountryCode":null,"NavigationModeCode":4,"MacAddress":"00-13-CE-80-4A-FF",
"RegisteredBySMS":false,"Disabled":false,"Sold":false,"AccountWithExpiration":false,"AccountExpiration":null,"TicketExpirationDate":null},
{"RegisteredUserID":14650...........
................
................
...............}]
Elenco completo delle API disponibili
Esempi in ASP.Net e PHP
Sono disponibili due esempi completi (Asp.net e PHP) che mostrano come effettuare l'autenticazione OAuth 2 e come effettuare le chiamate alle API:
- Panoramica
- Funzionalità
- Utenti registrati
- Modalità di navigazione
- Biglietti prepagati
- Piani tariffari
- Tariffe
- Gruppi di utenti
- Monitor delle connessioni
- Locations
- Captive portal
- Temi
- Info Portal Wi-Fi
- Pagamenti con carte di credito/PayPal
- Funzionalità WISP
- Autenticazione senza browser
- Registrazione tramite SMS
- Facebook Login
- WiFi4EU
- Ricariche prepagate
- Archivio sessioni
- Statistiche
- Operatori
- Gestione di Cassa
- Ricevute
- Preferenze
- Configurazione invio SMS ed EMail
- API per gli sviluppatori