WebIssues/Protocol

This section describes the design principles of the protocol used for communication between the WebIssues client and server.

The full specification of the protocol is available in Appendix A of the WebIssues Server manual.

Design

The WebIssues protocol is designed in order to support the client application in a most simple and efficient way. It contains only the minimal set of commands which are required by the client. It uses a very simplified syntax which minimizes the overhead and makes debugging easy.

One of the most common question regarding WebIssues is "why doesn't is use XML as the communication protocol?". First of all, XML is not a protocol, but merely a way to represent data. There are many protocols based on XML, such as XML-RPC or SOAP, there are also many alternatives like JSON or OGDL. None of them is "better" than others. The main disadvantage of XML is that it adds a lot of bloat - the tags significantly increase the amount of space and are just syntactic sugar. The WebIssues protocol was designed in such way that the data take the least amount of space possible but are still readable.

Also remember that the WebIssues system uses a 'rich client' architecture. It means that all logic is implemented on the client side. The server only provides commands for synchronizing data (for example, updating the list of issues) and for performing simple, atomic operations. Technologies such as Web Services are better suited for systems where most of the logic is implemented on the server side and the client only presents the results.

Embedding requests in a multipart/form-data message makes it possible to debug the server using a simple web page containing a form with one input field and file upload field. It also makes handling input data and file uploads trivial through built-in mechanisms of PHP.

Backward Compatibility

The general principle of WebIssues is that a client should work with both an older and a newer version of the server. Otherwise each upgrade of the server would require upgrading all client workstations and that can be pain.

Compatibility between the client and the server is very much like binary compatibility of shared libraries. New versions of a library can add new functions, but they cannot change the signature or the semantic of existing functions. So the most important principle of the WebIssues Protocol is that all commands and their results have a fixed syntax and semantics.

A newer version of the server can only add new commands, but it must not break compatibility with older clients. Backward compatibility affects not only the commands, but also other aspects of the protocol. For example, a new type of attribute cannot be added, because older clients would not know how to handle it and would report an error. A new preference field can be added and will be ignored by older clients, but changing the syntax or semantics of an existing field is not allowed.

Server Version

It is the client's responsibility to check the version of the server it's connecting to in order to determine which functions are available. The client should not use functions that are not supported by the server. The server's version is returned in the X-WebIssues-Server header (available since version 0.8.3).

The availability of some functions may depend on the configuration of the server. In order to determine which optional functions are enabled on a particular server, the LIST FEATURES command will be introduced in version 0.8.4. The client should not use functions which are not enabled.

Protocol Version

From time to time there is a need to make changes which are not backward compatible. That's for example the case if we decide that deleting or moving issues between folders should be possible. For that purpose the X-WebIssues-Version header is used (currently it's 0.8).

In general both the server and the client must use the same version of the protocol. The client will never work with a server using a newer version of the protocol. It may or may not have a compatibility mode for older versions, depending on the need and effort. The server doesn't need to know anything about the client; it's the client's responsibility to check the server's version.

The protocol version has never changed for the last three years. To reduce the impact, it will only be changed once a significant number of changes is gathered together and tested in the development version. Once this happens, the previous versions of both the client and server will remain maintained for some time until most users migrate to a new version.

Development Versions

The backward compatibility rules do not apply to development versions of the server. They can provide preliminary implementation of some functions which may be changed until the final version is released. Also the database schema can be changed until the final version. Because of that, beta version of the server should not be used for production.

In order to help avoid problems and overhead caused with changes in the protocol and schema in the development phase, a development version will have several limitations. First of all, upgrading the database schema will only be supported for official versions. It will not be possible to upgrade the database from a development version (although it would be possible to back up data, create a fresh installation and restore the data). Also the stable version of the client will not allow to connect to an older beta version of the server if there are any potential incompatibilities.