VSSF Core WebService
=============

Webservice return json response upon request.

DB schema
-------------
DB schema viewer is generated through schemaSpy, files are located under docs/db/schema


General
-------------
Every application is registered as a client of VSSF core service, and will be assigned to public key and secret key, and secret key should be kept as confidential.

One application need to acquire access token first, token has a expiration date and one application can has ONE and ONLY ONE valid token. Token is used HMAC-SHA256 hash and data is composed of timestamp + appid. Valid period of one token is configurable.

Once application has got a valid token, users belong to this application can use API as usual, given access token and post data.


User and application access permissions
-------------
One application can have several users and one user can belong to different applications.

One application can have several modules/hanlders registered (for example, DB module, usermanagement module etc.) One module/handler will have several actions (for example, usermanagement module will have login, logout, register actions). 

One user under given application belongs to given group, i.e. certain permission.

Permission is saved as json string in database, a typical permission example looks like as follows:

```
{"public":1,"anonymous":1,"admin":1,"users":1}
```


This simply means that user has all permissions.

One application modules and actions will also have permissions. Permissions one module level will apply for all actions on this module, and this permission can be overwritten by defining permission on module actions.



Message protocol
-------------
```
{
    authentication :    { 
    public_key : <String>
    appid : <String>
    token : <String>
    seesionid: <String>
    ip : <String>
}
    from :          {
                    appid : <String>
                    handlerid : <String>
}
    to :            {
                    appid : <String>
                    handlerid : <String>
}
    payload :       {
                    action : <String>
                    content : { … }
}
}
```


Examples
-------------
The following are two examples client can access vssf-core, 
it has to be a ajax post call.


* Request access token

    ``` 
    $url = "http://vssf-core.localhost/api/v1/auth/token"; 

    $data = '{"appid":"0987654321", "public_key":"1234567890"}'; 
    ```

* One message call

    ```
    $url = "http://vssf-core.localhost/api/v1/message/read"; 
    
    $data = array(
            'authentication' => array(
                'public_key' => '1234567890',
                'appid' => '0987654321',
                'token' => '4f64b443b675a669e52991c5a5daa93fd01f408b019df77ab2fdbc67cedf4a29',
                'ip' => Request::getClientIp(),
                'sessionid' => null
                ),
            'from' => array(
                'appid' => '0987654321',
                'handlerid' => 124,
                ),
            'to' => array(
                'appid' => '0987654321',
                'handlerid' => 3,
                ),
            'payload' => array(
                'action' => 'login',
                'content' => array(
                        'email' => 'user@user.com',
                        'password' => 'user'
                    ),
                )
            );
    ```