Created by Sylvain Carle, updated by Geneviève Bastien

= Wifidog API =

This page is used to define what data is exposed from the Auth Server thru and API for the purpose of using an independent CMS for the portal pages available to users.

== What ==

* UserInfo
 * Username
 * PasswordHash (or token)
 * DisplayName (nickname)
 * UserURL
 * UserAvatarURL
 * UserOtherInfo (?)

* HotSpotInfo
 * Name
 * Location
 * NetworkName
 * NetworkGroup (when in a HotSpot Collection, ie. "le village")
 * Uptime
 * ConnectedUsers

* NetworkInfo
 * NetworkName
 * NetworkUsersTotal
 * NetworkUsersOnline
 * NetworkHotSpotsTotal
 * NetworkHotSpotsOperational
 * SupportUrlForgotUsername
 * SupportUrlForgotPassword
 * SupportUrlForgotResendValidation


== How == 

''This is open for discussion and are only thoughts by gbastien''

Following on some other discussions on the wiki ([wiki:doc/developer/WiFiDog_V2] and [wiki:doc/developer/WiFiDogProtocol_V2]) 

The data should be requested and passed in standard ways, using a RESTful web service.

The request would be a simple http GET with the query string containing all necessary information to return the data.

Here are the possible parameters
||'''Parameter''' ||'''Possible values'''||'''Description'''||
||action||get,list|| What kind of action is requested from the service ||
||object_class||user, node, network|| What kind of data is requested ||
||object_id|| || The object id of the object whose details are being requested||
||fields || ||The fields to return ||
||f (optional default:json)||json,xml|| The format of the response (only json would be implemented for now) ||
||v (optional default:1.0)||1.0|| The version of the web service protocol (to be forward compatible, just in case) ||

A typical request would look like this
{{{
/ws/index.php?action=list&object_class=Node&&fields=name,connectedusers&f=json&v=1.0
}}}

The response would be in the form of a json string.  The advantages of json are discussed at other places on this wiki ().   The response would look something like this:
{{{
{
    {
        "name":"hotspot1name",
        "connectedusers":
         { 
             "user1": 
             {
                 "name":"user1name"
                 "url":"user1url"
             }
             "user2":
             {
                  "name":"user2name",
                  "url":"user2url"
             }
         }
    },
    {
         "name":"network2name",
         ...
    }
}
}}}

=== Some thoughts to keep in mind ===

While in the beginning, the purpose of this web service is to expose some data to CMS servers that will make use of it, we must keep in mind that we're opening another door on the auth server.  No data must pass through this door that wouldn't be publicly available anyway from the auth server.

As for more sensitive data that would usually require a certain level of permission, since there would be no session with this web service, we'd need a scheme to pass authentication data to the request that cannot be overheard.  SSL would be necessary for that, as some personal authentication data like a password or hash would be passed along the way.