Protocol

Introduction

This section will explain the underlying pinnings of the communication protocol.

Convention: In the example below

1. > means client to server -- i.e. upstream while
2. < means server to client -- i.e. downstream

Methods

A "method" is a function. You can call server-side functions from the client-side. For example:

> {
  "msg":"method",
  "id":"7",
  "method":"loginWithToken",
  "params":{"token":"1IGCKs8Upvg6LEzQgBwqc9PHQZCU5Lrv1UBAfRPv"}
}	
< {
  "msg":"result",
  "id":"7",
  "result":
    {
      "id":1,
      "instance":1,
      "email":"demo@test.oneoffice.ca"
      [....]
    }
  }	

The signature is always the same

1. Upstream: "method" defines the name of the function, and "params" is a JSON object containing the parameters. A unique serial "id" is generated by the client so it knows which response from the server correspond to that request.
2. Downstream: The server responds with "msg":"result" which means it's the resuld of a method call. The "id" is also sent back. "result" contains the returned result of the method call (if none -- a boolean true is returned)

In case of an error, instead of "result" you will get "error" field with a string error description. Example:

< {
  "msg":"result",
  "id":"7",
  "error":"not-allowed"
}

Subscriptions

As mentioned, our clients are designed to be data-driven. To get data from the server, you typically call the "sub" function. In some cases, you can also call methods to get data, but these are rare.

1. A subscription is reactive, if data you have received has changed (e.g. a file was renamed), you will get notified. Also if data is added (e.g. a new message), you will also get notified
2. A subscription allows your application to be data-drive, you subscribe to data and let the display handle it.

Three types of actions

A server can do one of three actions to a collection:

1. Added - a document (i.e. a row) was added to a collection. This is the equivalent of SQL INSERT
2. Updated - some fields in the document have changed. In SQL it is UPDATE
3. Removed - a document was removed. In SQL it is DELETE

A removed action does not mean the document was necessarily deleted server-side. It means the document is no longer visible by the client (e.g. they unsubscribed)

Complete Example

Here is a full example of a subscription

> {"msg":"sub","id":"11","name":"folder","params":{"parent":1}}	

< {
  "msg":"added",
  "collection":"files",
  "data":{"id":7,"instance":1,"owner":1,"name":"New File.docx",[...]}
  }	

< {
  "msg":"added",
  "collection":"files",
  "data":{"id":15,"instance":1,"owner":1,"name":"SOW - Ord. No. 126-18.pdf",[...]}
  }	

< {"msg":"ready", "id":11}

At the end of this transmission, the client-side collection "files" shoud have two documents, one with id 7 and one with id 15

Updated Example

Let's say we renamed the file with id 7

< {
  "msg":"updated",
  "collection":"files",
  "data":{"id":7,"name":"New name.docx"}
  }	

Note how only changed fields are sent down .. it is the client's responsibility to do proper merging of fields

Removed example

Let's say file with id 7 is no longer visible client-side. The client will have to react by removing the document with id 7 from its collection (and the UI will refresh accordingly).

< {
  "msg":"removed",
  "collection":"files",
  "id":7
  }	

Added Example

Let's say a new file was added

< {
  "msg":"added",
  "collection":"files",
  "data":{"id":16,"name":"Business case.xlsx", [...]}
  }	

Notice that the signature is different here, we do not have "data" field, but "id" only