Difference between revisions of "WebIssues/Protocol"
| Line 1: | Line 1: | ||
This is a description of the design principles of the protocol used for communication between the WebIssues client and server. | This is a description of the design principles of the protocol used for communication between the WebIssues client and server. | ||
| − | |||
| − | |||
== Design == | == Design == | ||
| Line 7: | Line 5: | ||
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 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 fields separated by spaces. | + | 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. | 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. | ||
| Line 19: | Line 17: | ||
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. | 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 | + | 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 == | == Protocol Versions == | ||
| − | The | + | The version of the protocol 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, which can be identified by the X-WebIssues-Version header. 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). |
| − | + | Patch versions are insignificant, so generally 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 possible to extend the protocol between different versions of the server and the client, 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. | It is possible to extend the protocol between different versions of the server and the client, 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 it can provide preliminary implementation of some functions which may be significantly changed before the final version is released. In such case the protocol version is also marked with appropriate alpha or beta sub-version. Development versions of the server can only be used with the same version of the client | + | During development the protocol can change between each version of the server and it can provide preliminary implementation of some functions which may be significantly changed before the final version is released. In such case the protocol version is also marked with appropriate alpha or beta sub-version. 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. |
Revision as of 20:33, 12 December 2011
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 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, which can be identified by the X-WebIssues-Version header. 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).
Patch versions are insignificant, so generally 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 possible to extend the protocol between different versions of the server and the client, 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 it can provide preliminary implementation of some functions which may be significantly changed before the final version is released. In such case the protocol version is also marked with appropriate alpha or beta sub-version. 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.
