<commit_before>System Architecture and Protocol
================================

The system follows a client/server architecture. Expected clients are: web,
mobile phone, console and libraries. The server is required to be a RESTful
application (see [Representational state transfer]
(http://en.wikipedia.org/wiki/Representational_state_transfer)).

_Add here some explanations about REST:_
* HTTP requests,
* URLs for resources
* HTTP verbs for methods
* Status codes for results
* Request and results contents

The server thus is defined by its __resources__ and the __actions__ allowed
on them. This solution is adapted to the system (_why?_), is simple to
implement (_reference?_) and has several advantages (_over what? which
advantages?_).

This document defines:
* the resources, their contents and their representations,
* the supported methods, their inputs, outputs and status codes.



Resources
---------

The system makes use of the following resources:
* users,
* formalisms,
* models,
* converters,
* scenarios,
* services,
* executions,
* projects.

_Here we are missing a document that presents all these notions. Perhaps
you should write another sheet on `requirements`._

To identify resources, REST uses [Uniform Ressource
Identifiers](http://fr.wikipedia.org/wiki/Uniform_Resource_Identifier)
(URIs). A client requests a resource to the server by providing it with the
URI of the resource. There are two kinds of resources in this application:
* __resources collections__;
* __resources__.
They are distinguished by the use of the singular form (for single resources)
or the plural form (for resources collections).

For instance,
 * `/users/` represents a collection of users;
 * `/users/rokysaroi` represents the user `rokysaroi` in the `users`
   collection.

_You should also tell about the hierarchy of resources. Some resources can
or must be put within other ones._

The server exposes the following resources. A resource name starting with
`:`, for instance `:user`, is a variable. The following list also shows the
hierarchy of resources. The notation `(a|b)` tells that a resource is
available for prefixes `a` and `b`.

* `/`: _explain_
* `/users`:
* `/projects`:
* `/(users|projects)/:id`:
* `/(users|projects)/:id/formalisms`:
* `/(users|projects)/:id/formalisms/:formalism`:
* `/(users|projects)/:id/formalisms/:formalism/converters`:
* `/(users|projects)/:id/formalisms/:formalism/converters/:to`:
* `/(users|projects)/:id/models`:
* `/(users|projects)/:id/models/:model`:
* `/(users|projects)/:id/scenarios`:
* `/(users|projects)/:id/scenarios/:scenario`:
* `/(users|projects)/:id/services`:
* `/(users|projects)/:id/services/:service`:
* `/(users|projects)/:id/executions`:
* `/(users|projects)/:id/executions/:execution`:
* `/users/:id/projects`:
* `/users/:id/projects/:project`: redirects to a project
* `/projects/:id/users`:
* `/projects/:id/users/:user`: redirects to a user



A resource is can have several representations (XML, JSON, image, CosyVerif
format, CAMI, PNML, ...). Internally, the server uses the CosyVerif
representation for the following resources: formalism, model, scenario,
service, execution.

Clients are allowed to ask for a particular representation in their
requests. Whenever possible, the server performs a conversion of the
resource to the required format.

### Example: representation of a collection of resources and a resource

````xml
<user xmlns='http://example.org/mon-exemple-ns/'>
  <first-name>First name</first-name>
  <last-name>Last name</last-name>
  <login>User name</login>
  <phone>Phone number</phone>
</user>
````
````json
  {
    "user": {
      "first-name" : "<NAME>",
      "last-name" : "<NAME>",
      "login" : "<NAME>",
      "phone" : "Phone number"
    }
  }
````
````xml
<users xmlns='http://example.org/mon-exemple-ns/'>
  <user-ref href="first user URI">complete name first user</user-ref>
  <user-ref href="second user URI"/>complete name second user</user-ref>
  ...
  <user-ref href="last user URI"/>complete name last user</user-ref>
</users>
````
````json
{
  "users": {
    "user-ref" : [
      {"href" : "First user URI", "name" : "complete name of first user"},
      {"href" : "Second user URI", "name" : "complete name of second user"},
      ...
      {"href" : "Last user URI", "name" : "complete name of last user"}
    ]
  }
}
````

 _The presentation of all representation formats resources here ......_.




Methods and status codes
------------------------

The REST architecture is based on the `HTTP` protocol. Therefore, the same methods are more or less used 
the latter to take advantage of its standardization. Agents can use a URI to access the referenced resource. <commit_msg>Update code blocks to set their language.<commit_after>System Architecture and Protocol
================================

The system follows a client/server architecture. Expected clients are: web,
mobile phone, console and libraries. The server is required to be a RESTful
application (see [Representational state transfer]
(http://en.wikipedia.org/wiki/Representational_state_transfer)).

_Add here some explanations about REST:_
* HTTP requests,
* URLs for resources
* HTTP verbs for methods
* Status codes for results
* Request and results contents

The server thus is defined by its __resources__ and the __actions__ allowed
on them. This solution is adapted to the system (_why?_), is simple to
implement (_reference?_) and has several advantages (_over what? which
advantages?_).

This document defines:
* the resources, their contents and their representations,
* the supported methods, their inputs, outputs and status codes.



Resources
---------

The system makes use of the following resources:
* users,
* formalisms,
* models,
* converters,
* scenarios,
* services,
* executions,
* projects.

_Here we are missing a document that presents all these notions. Perhaps
you should write another sheet on `requirements`._

To identify resources, REST uses [Uniform Ressource
Identifiers](http://fr.wikipedia.org/wiki/Uniform_Resource_Identifier)
(URIs). A client requests a resource to the server by providing it with the
URI of the resource. There are two kinds of resources in this application:
* __resources collections__;
* __resources__.
They are distinguished by the use of the singular form (for single resources)
or the plural form (for resources collections).

For instance,
 * `/users/` represents a collection of users;
 * `/users/rokysaroi` represents the user `rokysaroi` in the `users`
   collection.

_You should also tell about the hierarchy of resources. Some resources can
or must be put within other ones._

The server exposes the following resources. A resource name starting with
`:`, for instance `:user`, is a variable. The following list also shows the
hierarchy of resources. The notation `(a|b)` tells that a resource is
available for prefixes `a` and `b`.

* `/`: _explain_
* `/users`:
* `/projects`:
* `/(users|projects)/:id`:
* `/(users|projects)/:id/formalisms`:
* `/(users|projects)/:id/formalisms/:formalism`:
* `/(users|projects)/:id/formalisms/:formalism/converters`:
* `/(users|projects)/:id/formalisms/:formalism/converters/:to`:
* `/(users|projects)/:id/models`:
* `/(users|projects)/:id/models/:model`:
* `/(users|projects)/:id/scenarios`:
* `/(users|projects)/:id/scenarios/:scenario`:
* `/(users|projects)/:id/services`:
* `/(users|projects)/:id/services/:service`:
* `/(users|projects)/:id/executions`:
* `/(users|projects)/:id/executions/:execution`:
* `/users/:id/projects`:
* `/users/:id/projects/:project`: redirects to a project
* `/projects/:id/users`:
* `/projects/:id/users/:user`: redirects to a user



A resource is can have several representations (XML, JSON, image, CosyVerif
format, CAMI, PNML, ...). Internally, the server uses the CosyVerif
representation for the following resources: formalism, model, scenario,
service, execution.

Clients are allowed to ask for a particular representation in their
requests. Whenever possible, the server performs a conversion of the
resource to the required format.

### Example: representation of a collection of resources and a resource

One user in `XML`:

````xml
<user xmlns='http://example.org/mon-exemple-ns/'>
  <first-name>First name</first-name>
  <last-name>Last name</last-name>
  <login>User name</login>
  <phone>Phone number</phone>
</user>
````

The same in `JSON`:

````json
{
  "user": {
    "first-name" : "<NAME>",
    "last-name" : "<NAME>",
    "login" : "User name",
    "phone" : "Phone number"
  }
}
````

A collection of users in `XML`:

````xml
<users xmlns='http://example.org/mon-exemple-ns/'>
  <user-ref href="first user URI">complete name first user</user-ref>
  <user-ref href="second user URI"/>complete name second user</user-ref>
  ...
  <user-ref href="last user URI"/>complete name last user</user-ref>
</users>
````

The same in `JSON`:

````json
{
  "users": {
    "user-ref" : [
      {"href" : "First user URI", "name" : "complete name of first user"},
      {"href" : "Second user URI", "name" : "complete name of second user"},
      ...
      {"href" : "Last user URI", "name" : "complete name of last user"}
    ]
  }
}
````

_The presentation of all representation formats resources here ......_.




Methods and status codes
------------------------

The REST architecture is based on the `HTTP` protocol. Therefore, the same methods are more or less used 
the latter to take advantage of its standardization. Agents can use a URI to access the referenced resource. 
{'fraction_non_alphanumeric': 0.14206215875682487, 'fraction_numerical': 0.0, 'mean_word_length': 4.2770083102493075, 'pattern_counts': {'":': 4, '<': 44, '<?xml version=': 0, '>': 44, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 8}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3555485', 'n_tokens_mistral': 2814, 'n_tokens_neox': 2708, 'n_words': 1031}