MyWiFi

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.
In risposta lo sviluppatore riceverà due chiavi di accesso (client_id e client_secret) da utilizzare nella procedura di autenticazione OAuth2.

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:

Esempio api php
Esempio Client PHP

Esempio api asp.net
Esempio Client ASP.Net