CoOPS protocol specification 1.0.0

OVERVIEW

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.

STATUS

Protocol version is currently 1.0.0

REST API

Status Codes

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.

(GET) / (load request)

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"
  }
}

(GET) /update (update request)

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
    }
  }
}, ... ]

(PATCH) / (patch request)

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.

(GET) /join (join request)

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"
    }
  }
}