HTTP Principles

Before any technical details of Cytomine, we will briefly resume the HTTP principles, the REST architecture and the JSON format which will be mainly used to share the datas.

The HTTP

The HyperText Transfer Protocol (HTTP) is a client-server communication protocol. He is mainly used by the web browsers which want to exchange datas with servers (HTML pages, images, ...). A HTTP request always contains an adress (URL) and a method. The URL identify the server and the remote resource in which we want to access. The method is used to determine the request type. In this project, we will used the following methods:

The JSON format

The JavaScript Object Notation (JSON) is a data format which allow a textual representation of structural information. Despite its Javascript notation, it is language-free and mainly supported by various programming language.

A document written at the JSON format is composed of :

There exists 3 data types :

Use

The JSON format is mainly used by web interfaces for the following arguments :

Basical example

For this example, we will describe a user resource of Cytomine into JSON format by this way :

{
    "username": "johndoe",
    "firstname": "john",
    "lastname": "doe",
    "password": "doedoe2011",
    "authorities": [
        "Regular",
        "Administrator"
    ]
}

Each time a HTTP request is done on a server and it returns the asked resource into JSON format, these resource can be evaluated in the following way :

{
    /* Evaluation of an USER object contained in the variable "data" */
    var user = eval('('+data+')');
    /* Display username */
    var username = user.username;
    console.log(username);
}


In the other way, we can encode a Javascript object at the JSON format like in the following code. Once at the JSON format, the resource can be send to the server.

{
    /* Evaluation of an USER object contained in the variable "data" */
    var user = eval('('+data+')');
    var user.username = "john2";
    /* We write the user in a JSON string */
    var jsonUSER = JSON.parse(user);
    ...
}

REST

Representational State Transfer (REST) is a way to organize an application for distributed systems. REST is not a protocole neither a format and must be seen as a architectural style. A REST application follow some simple rules :