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?

* HotSpotInfo?

* NetworkInfo?

Ben: While we may want to completely change the format, much of this information is already available in XML format from the auth server at hotspot_status.php?format=XML

How

This is open for discussion and are only thoughts by gbastien

Following on some other discussions on the wiki (doc/developer/WiFiDog_V2 and 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 valuesDescription
actionget,list,auth What kind of action is requested from the service
object_classuser, 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
v (optional default:1)1 The version of the web service protocol (to be forward compatible, just in case)
additional parameters any additional parameter needed by the requested action

A typical request would look like this

/ws/index.php?action=list&object_class=Node&object_id=1234&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:

{
    {
        "result":"1",
        "values":
        [{
           "name":"hotspot1name",
           "connectedusers":
            { 
               "user1": 
               {
                  "name":"user1name"
                  "url":"user1url"
               }
               "user2":
               {
                  "name":"user2name",
                  "url":"user2url"
               }
            }
         },
         {
            "name":"network2name",
            ...
         }]
    }
}

Should an exception occur in the web service, it would be returned in the requested format of output like this:

{   
    "result":0,
    "values":
    {
        "type":"WSException",
        "message":"Detailed error was: Uncaught WSException Action gabc is not defined. Please use GET parameter 'action=list|get|auth' to specify an action (0) thrown in file /var/www/wifidog-auth/wifidog/ws/classes/WifidogWS/V1.php, line 114"
    }
}

The equivalent XML string would be the keys as element names the values as value. Unkeyed elements will be enclosed in a <item></item> tag. The top-level Xml tag is <WiFiDogWebService?>

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.

Ben: Pretty much by definition of the scope of this API, we need to establish some sort of shared session between the "content" server and the auth server. To avoid complexity, passing a huge amount of data the content server may or may not need, I think we must pass a session-identifier equivalent (we should at least prevent dictionary attacks from the start) to the content server during the initial redirect, and mandate SSL. This way, the content server can request as much, or as little data from the server as it wants, and can only do so for an active session (for user specific information).