CoOPS is a protocol which allows users to simultaneously edit a file in a server. The protocol focuses on the core of the simultaneous editing, leaving out other functions - such as user management, file creation, file deletion, etc. These functions are extensions to the basic protocol. The protocol defines the client-server communication using HTTP protocol.
The protocol assumes that each file is located in an address that can be used for file identification (URL). All protocol operations are relative to this address. This allows the protocol to be used in variety of different contexts, such as editing of html document, a paragraph of a wiki page or a svg image. Because the editing environment (blog, wiki, etc. server program) usually contains user registration and authentication functions these are left out of the scope of protocol. Communication between server and client is done via HTTP protocol using JSON formatted data.
Protocol also defines way to transfer meta-information besides normal file content.
It makes sense to use different diff / patch algorithms for different file types. For this reason, client and the server negotiate used diff / patch algorithm before starting.
Protocol version is currently 1.0.0
| 200 - OK | Used when request has succeeded. |
| 404 - Not Found | When requested file could not be found |
| 409 - Conflict | When request has failed because of a conflict |
| 500 - Internal Server Error | When request has failed unexpectedly |
| 501 - Not Implemented | When client has requested for a unsupported feature |
Implementations may use other status codes besides ones used in protocol.
Returns a file and file meta-information. If revision number parameter is specified method returns file of that specified revision otherwise last revision is returned
| Path | / |
| Method | GET |
| Errors | |
| 404 - Not Found | When file does not exist |
| Parameters | |
| revisionNumber | (Query) Optional parameter that specifies file revision to be returned. |
Response
Status code should be 200 when request is successful.
| revisionNumber | Revision number of a returned file. |
| content | Contents of the file as text. Binary files are serialized into text form |
| contentType | Content type of the file. If file needs to be edited by some specific editor "editor" -parameter can be used to specify which one |
| properties | File metadata as key-value pairs (JSON Object). |
Example response
{
"revisionNumber": 123,
"content": "CONTENT",
"contentType": "text/html;editor=CKEditor",
"properties": {
"name": "Name of the file",
"backgroundColor": "green"
}
}
Client calls the method in order to check new updates into the file.
| Path | /update |
| Method | GET |
| Errors | |
| 400 - Bad request | When revisionNumber parameter is missing |
| Parameters | |
| sessionId | (Query) Unique collaboration session id. |
| revisionNumber | (Query) Revision number of client file. |
Response
Status code should 200 (OK) when server has updates for client and 204 (No Content) when updates are not available. When server sends 204 no content should be sent.
| sessionId | Unique collaboration session id |
| revisionNumber | Revision number of the patch |
| checksum | Content checksum for integrity checks (optional) |
| patch | Changes into the file content in used diff format |
| properties | Changed properties as key-value pairs (JSON Object) |
| extensions | Changed extension values as key-value map (JSON Object). Extension names act as keys and changes are represented in key-value pairs (JSON Object) |
Example response
[{
"sessionId": "1a79a4d60de6718e8e5b326e338ae533",
"revisionNumber": 123,
"checksum": "1a79a4d60de6718e8e5b326e338ae533",
"patch": "patch text",
"properties": {
"name": "Name of the file",
"backgroundColor": "green"
},
"extensions": {
"cursors": {
"selectStart": 199,
"selectEnd": 200
}
}
}, ... ]
Patches a file.
| Path | / |
| Method | PATCH |
| Errors | |
| 404 - Not Found | When file does not exist |
| 409 - Conflict | When server file revision does not match client file revision |
| Parameters | |
| sessionId | (JSON) an unique collaboration session id |
| revisionNumber | (JSON) a number of revision patch is meant for |
| patch | (JSON) an optional field that contains changes to the file content in used diff format |
| properties | (JSON) an optional field that contains changed metadata as key-value pairs (JSON Object) |
| extensions | (JSON) an optional field that contains extension changes as key-value pairs (JSON Object) |
Response
Successful request returns status code 204 (No Content) and does not return any content.
Client calls the method in order to join the collaboration session.
| Path | /join |
| Method | GET |
| Errors | |
| 404 - Not Found | When file does not exist |
| 501 - Not Implemented | When server does not support any algorithms provided by client and/or when unsupported CoOPS version is specified |
| Parameters | |
| algorithm | (Query) algorithm(s) supported by client. Parameter can be repeated to indicate support for multiple algorithms. In this case algorithms should be ordered descendingly from most favourable to least favourable algorithm |
| protocolVersion | (Query) used CoOPS protocol version. |
Response
Status code should be 200 if the request is successful
| sessionId | Unique collaboration session id |
| algorithm | Revision number of returned file. |
| revisionNumber | Current revision number of the file |
| content | Current content of the file |
| contentType | Current content type of the file |
| properties | Current properties of the file as key-value pairs (JSON Object) |
| extensions | Supported extensions as key-value map (JSON Object). Extension names are listed as keys and values are settings of extension as key-value pair (JSON Object) |
Example response
{
"sessionId": "1a79a4d60de6718e8e5b326e338ae533",
"algorithm": "diff-match-patch",
"revisionNumber": 123,
"content": "CONTENT",
"contentType": "text/html;editor=CKEditor",
"properties": {
"name": "Name of the file",
"backgroundColor": "green"
},
"extensions": {
"websockets": {
"unsecureWebSocketUrl": "ws://www.example.com:80/path/to/file/token",
"secureWebSocketUrl": "wss://www.example.com:8443/path/to/file/token"
}
}
}