WebIssues/Protocol

From MiMec
Jump to: navigation, search

This section describes the protocol used for communication between the WebIssues client and server. This is work in progress, for now only the backward compatibility problem is described.

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

Backward Compatibility

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

Because of this, the changes to the communication protocol should be backward compatible. It means that the syntax and semantic of existing commands cannot be changed, but new commands can be added. This is very much like binary compatibility of shared libraries.

Server Version

The client should check the version of the server it's connecting to. If the version of the server is newer than the latest known version, the client will simply not take advantage of the new functions that are available. If the version of the server is older, the client will disable 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).

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).

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 required to maintain such compatibility. The server doesn't need to know anything about the client and it will always use only one version of the protocol. It's the client's responsibility to check and adjust to the server's version.

To reduce the impact of changing the protocol version, this should be done as rarely as possible. Multiple changes should be merged together and they should be only done in the development version until a production version is released. Also the previous version of both the client and server should remain maintained for some time (bug fixes etc.).