Web service layer

In order to provide the functionality of PhpReport to external applications, independently of the programming language, a layer of web services has been created.

Design

The design of the services is inspired by the REST architectural style. They use the protocols and standards already defined by the World Wide Web to model and implement the services. Mainly, it's based in the HTTP protocol for access to resources and the exchange of messages between the client and the web service.

The services are located in the URL web/services/ in the server hosting PhpReport. They use the HTTP operations GET and POST to receive and send data, respectively; with both operations, using additional parameters in the URL of the service, it is enough for us to implement all the needed tasks. It can not be said that the services follow REST strictly, since the URLs do not represent resources, but operations, and the operations PUT and DELETE are not used.

Classification of services

Regarding the type of client going to use the services, can distinguish two types:

Services intended to be used by external applications. These services can be used either by the external customers or by the user web interface.
Services created specifically to support the user web interface. The difference is these services have little utility outside of the web interface. They usually contain metainformation for visual configuration of the UI widgets.

And regarding the language of the messages transmitted, there are:

Services using XML; the majority of them.
Services using JSON; some services in which the client (usually a specific widget in the UI) demands it.

Session management

PHP session management has to be considered in the implementation of web services. This is usually handled by the web browser transparently for both users and programmers. It may use cookies or GET parameters in case the former are not available. However, when the client is not a browser, programmers have to take session management into account explicitly.

Session management uses a login service that returns an identification token when the operation finishes properly. This token is associated to the PHP session PHP so that, in future requests to web services, the client has to send the token as a parameter so the application can associate it to some active session. This manual management is unnecessary in the case of the web interface because the browser takes care of this transparently.

Therefore, only external client applications using PhpReport services should take session management as explained here into account.

Usage

To illustrate the operation of web services, we will show the messages exchanged in the case of the task creation service. A summary of this interaction can be seen in the next sequence diagram:

To begin with, we have to authenticate using the login service. We invoke the service URL, sending the authentication credentials in the HTTP Authorization header:

GET /phpreport/web/services/loginService.php HTTP/1.1
Host: localhost
Authorization: Basic b'YWRtaW46YWRtaW4='

If the login data were correct, it returns:

<?xml version="1.0"?>
<login>
    <sessionId>elr51a4trslb07qo5lngcq0ef0</sessionId>
</login>

We have to use the sessionId that we have received to call the URL of the task creation service, using a operation POST the following way:

POST /phpreport/web/services/createTasksService.php?sid=elr51a4trslb07qo5lngcq0ef0

The content of the POST request is this XML message, generated by the client:

<?xml version="1.0"?>
<tasks>
    <task>
        <date>2009-10-29</date>
        <initTime>00:00</initTime>
        <endTime>03:00</endTime>
        <customerId>10</customerId>
        <projectId>196</projectId>
        <ttype>hjgjhg</ttype>
        <story>jhgjhgjk</story>
        <text>uyefsdgfdghfdhgf</text>
        <telework>true</telework>
    </task>
    <task>
        ...
    </task>
</tasks>

Whereas the application will answer like this in case of success:

<?xml version="1.0"?>
<return service="createTasks">
    <success>true</success>
    <ok>Operation Success!</ok>
    <tasks>
        <task>
            <id>149620</id>
            <date>2009-10-29</date>
            <initTime>00:00</initTime>
            <endTime>03:00</endTime>
            <customerId>10</customerId>
            <projectId>196</projectId>
            <ttype>hjgjhg</ttype>
            <story>jhgjhgjk</story>
            <text>uyefsdgfdghfdhgf</text>
            <telework>true</telework>
        </task>
        <task>
            <id>149621</id>
            ...
        </task>
    </tasks>
</return>

Or like this, in case of error:

<?xml version="1.0"?>
<return service='createTasks'>
    <success>false</success>
    <error id='2'>You must be logged in</error>
</return>

Notice that this service returns a list with the tasks that have been saved, in case of success, but including an additional piece of data: the internal identifier of the task. In successive calls, the client has to use this identifier to update the data of the task.

Testing the services

The page web/APITest.php can be used to test the services. It provides a field to set the service URL, and another field to set the content of the POST request. After the "Send" button is hit, the response will be printed on-screen.

Please, notice that PhpReport releases do not include this test page, developers must have created a development environment. Besides, they must be logged in as an admin to be able to access it.