WebIssues/Protocol
This is a description of the design principles of the protocol used for communication between the WebIssues client and server.
Design
The WebIssues protocol is designed to support communication between the desktop client and the server in a simple and efficient way. It contains only a minimal set of commands and uses a very simplified syntax to minimize the overhead and make implementation and testing easy.
The protocol is based on HTTP request-response communication model. The request is a multipart/form-data message which is commonly used by web browsers to submit form data with attached files. It consists of a mandatory 'command' field and an optional 'file' field. Such format is very natural and easy to handle by the PHP-based server application. The command consists of one or more keywords and a number of arguments separated by spaces. The response is a plain text message which consists of zero or more records, each in a separate line, with a keyword and a number of fields separated by spaces.
No additional tags or other kind of markup is necessary, because the protocol is well defined and the meaning of each field is known to both the client and the server. Traditional protocols based on XML, such as XML-RPC or SOAP, and other alternatives like JSON or OGDL, are not efficient for transferring large amounts of data because they contain too much bloat. The WebIssues protocol does not depend on any specific language or technology and can be easily parsed by any kind of application.
Commands defined in the protocol can be divided in two groups: commands for retrieving data from the database and commands for performing modifications in the database. The first group of commands is used to synchronize data between the client and the server (see Architecture for more information) and they simply return all data from one or more tables (filtered according to user permissions). Modification commands are used to perform add/update/delete operations requested by the user. They check user permissions, ensure validity and integrity of data and usually return no information (except for the identifier of created item).
Incremental Updates
Some lists such as the list of projects and folders or list of users contain relatively small amount of data so they can be efficiently updated as a whole. On the other hand, the list of issues in a folder (including attribute values) and the details of an issue (including comments and changes) can be very large, so it would be very inefficient to always retrieve all data. This is why a mechanism of incremental updates was created.
Each operation related to an issue - including adding a new issue, comment or attachment and changing the value of an attribute - is related with a unique incrementally growing value called the 'stamp'. Identifiers of issues, comments, attachments and changes are directly related to their stamps. In addition, each folder and issue holds a 'last modification stamp' which allows to quickly find which items were modified since the last update. The LIST ISSUES and GET DETAILS commands allows passing a stamp value and only items created or modified after the given stamp are returned.
The mechanism of incremental updates was extended in version 1.0 to allow e.g. deleting and moving issues between folders. Such operations are tracked by the server in form of 'stubs', which also have their stamps, and returned to the client if necessary.
Protocol Versions
The version of the protocol is identified by the X-WebIssues-Version header. It is generally the same as the two first digits of the server version, for example 0.8 or 1.0. The client can communicate with a server using the same version of the protocol. It may also support older versions of the protocol (for example, version 1.1 of the client might support version 1.0 of the server). It should also be possible to install two versions of the client, which support different servers (for example, 0.8 and 1.0), side by side.
Patch versions are insignificant, so client 1.0.2 will work with server 1.0.1 and vice-versa, because the same version of the protocol is used. Because of this, backward incompatible changes in the protocol are prohibited between patch versions.
It is however possible to extend the protocol without changing the protocol version, as long as the syntax and semantics of existing commands remains unchanged. It is also possible to enable or disable some functionality depending on the configuration of the server. The client should detect the capabilities of the server and use the additional features only if possible.
During development, the protocol can change between each version of the server, and the protocol version is marked as alpha or beta. Development versions of the server can only be used with the same version of the client. The stable version of the client will not allow to connect to a development version of the server.
