Server Client Protocol

Server-Client Protocol

This page describes the protocol used to communicate between the server and client. We use a simple protocol over HTTP that uses actions, which is an HTTP request argument (possible in combination with a additional arguments, see below) and returns a JSON response.

Actions

Actions are sent by the client over HTTP, the action itself is specified by the string given for the action argument. A request may contain additional arguments, some which are required or optional for the given action. Additional arguments which are not specified by the action are ignored by the server.

Responses

This section discusses the rationale and inner-workings of the server responses.

Structure

Responses consists of well-formed JSON, see the brief example below:

Content-Type: application/json

{
  "action": "action_string", 
  "messages": [], 
}

A response consists of attributes which corresponds to the requested actions and attributes which may or must be in each response, these protocol attributes are:

action: a response may contain the string which corresponds to the action requested by the client, the server must set this attribute if the requested action was successful, but may leave it out if it encounters issues processing the action, if that is the case the server must set the exception attribute of the response
messages: if present this attribute is an array of messages which are arrays of length three on the format: ["${MESSAGE_STRING}", "${TYPE}", ${DURATION}], these messages are not intended to be handled programatically but to be displayed to the user as-is
exception: a part of the server-client exception handling protocol, if present it must be either a string or true, a string encodes a specific exception which has occurred (e.x. "notAuthorised" if the user is not logged in and requests and action that requires authorisation)

Most exceptions are unique to an action, but the one(s) below may be raised for any action:

notImplemented: the server does not implement the requested action although it is specified by the protocol

Server-Client Initialisation Sequence

Server-Client Initialisation Sequence Diagram

Actions Listing

getCollectionInformation

Request information relevant for a given collection of documents.

Arguments

TBD: Explain the "collection" concept somewhere, and this really is a collection specifier

collection: document collection for which to return information concerning

Response

attribute_types: TBD
entity_types: TBD
event_types: TBD
header: TBD
items: TBD
parent: TBD
relation_types: TBD

Exception(s)

collectionNotAccessible: cannot access collection due to e.g. filesystem permissions

login

Verify with the server that you are a registered user to gain access to actions requiring a login.

Arguments

user: username found in config.py
password: matching password from config.py

Response

None

Exception(s)

invalidAuth: if the credentials do not match

retrieveSVG

Retrieve the current SVG from the SVG-store.

Arguments

version: version of the SVG to return, can be colour or greyscale
document: used in document disposition to fake to the client that the data has the filename ${document}.svg

Response

Warning: This action violates protocol since it does not return JSON, instead it returns the SVG data

Exception(s)

noSVG: if no SVG is in the SVG-store
unknownSVGVersion: if the given version argument is not colour or greyscale

storeSVG

Inserts an SVG into the SVG-store, the SVG-store can contain at most one SVG at the time on a per-user basis. Inserting additional SVG;s will overwrite the older versions.

Arguments

svg: SVG data to store

Response

None

Exception(s)

corruptSVG: if what is given is not valid SVG data

Protocol Changes

Listing of all changes in protocol, refer to the revision where/when it was introduced.

Resources

This is considered a part of the documentation of brat and resources are found under doc/. This includes sequence diagrams which we generate using mscgen.