--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/design/api/metacategory.apib Mon Jul 17 14:13:32 2017 +0200
@@ -0,0 +1,248 @@
+FORMAT: 1A
+
+# API
+
+Documentation de l'API d'édition des protocoles d'annotation.
+
+Tous les endpoint de cet API demande une authentification par token.
+Toutes les requêtes doievnt donc comporter l'en-tête suivant :
+```http
+Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
+```
+
+# Data Structures
+
+## Protocol (object)
+
+- id: `a4977c1f-4752-4aff-b724-eec4033af25c` (string)
+- owner: `group1` (string)
+- revision_number: `5` (number)
+- last_description: `Cras rutrum lacinia pretium. Suspendisse justo est, tincidunt sed tellus a, sodales suscipit risus. Curabitur odio tortor, tincidunt sed est nec, ullamcorper sodales velit.` (string)
+
+
+## ProtocolRevision (object)
+
+- id: `a4977c1f-4752-4aff-b724-eec4033af25c` (string)
+- owner: `group1` (string)
+- revision: `1`
+- description: `Cras rutrum lacinia pretium. Suspendisse justo est, tincidunt sed tellus a, sodales suscipit risus. Curabitur odio tortor, tincidunt sed est nec, ullamcorper sodales velit.` (string)
+
+## MetacategoryRevision (object)
+
+- id: `e5712a76-857a-4769-b27e-a3ac3fb38b4d` (string)
+- revision: `2` (number)
+- base: `ef14bcce-52ac-44ba-a7d1-f1441bab94de` (string)
+- name: `référence` (string)
+- description: `Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin massa nibh, hendrerit quis justo vitae, luctus tempor dolor. Nam quis fringilla diam.` (string)
+- color: `#2cbfff` (string)
+- has_comment: `false` (boolean)
+
+## ProtocolRevisionFull (object)
+
+- Include MetacategoryRevision
+- metacategories (array[MetacategoryRevision])
+
+
+## Collection de protocoles [/protocol/{?page,page_size}]
+
+### Voir la liste des protocoles [GET]
+
+Liste les protocoles pour une application. L'application est déterminée par le token passé comme authentification.
+
++ Parameters
+
+ + page: `3` (number, optional) - Get the page.
+ + Default: `1`
+ + page_size: `15` (number, optional) - Set number of protocol per page
+ + Default: `10`
+
+
++ Request
+ + Headers
+
+ Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
+
++ Response 200 (application/json)
+
+ + Attributes
+ - count: `15` (number)
+ - next: `http://scatedit.episteme.fr/api/protocol/?page=2`
+ - prev: `null`
+ - `results` (array[Protocol], fixed-type)
+
+### Créer un nouveau protocole [POST]
+
+Crée un nouveau protocole d'annotation dont la liste des méta-catégorie est la liste des méta-catégories par défaut pour l'application.
+
+Le numéro de révision retourné sera toujours `1`.
+
++ Request (application/json)
+
+ + Headers
+
+ Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
+
+ + Attributes
+ - owner: `group1` (string)
+ - description: `Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin massa nibh, hendrerit quis justo vitae, luctus tempor dolor. Nam quis fringilla diam.` (string)
+
+
++ Response 201 (application/json)
+
+ + Attributes (ProtocolRevisionFull)
+
+## Révisions d'un protocole. [/protocol/{id}/{?page,page_size}]
+
+### Voir la liste des revision pour un protocole [GET]
+
+Liste les revisions d'un protocole pour une application.
+
++ Parameters
+
+ + id: `a4977c1f-4752-4aff-b724-eec4033af25c` - Identifiant d'un protocole
+ + page: `3` (number, optional) - Get the page.
+ + Default: `1`
+ + page_size: `15` (number, optional) - Set number of protocol per page
+ + Default: `10`
+
++ Request
+ + Headers
+
+ Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
+
+
++ Response 200 (application/json)
+
+ + Attributes
+ - count: 15
+ - next: http://scatedit.episteme.fr/api/protocol/a4977c1f-4752-4aff-b724-eec4033af25c?page=2
+ - prev: null
+ - results (array[ProtocolRevision])
+
++ Response 403
+
+ Retournée si l'utilisateur (application) n'est pas le propriétaire du protocole.
+
+ + Attributes (object)
+ - error : `Application is not protocol owner.`
+
++ Response 404
+
+ Retournée si l'identifiant ne coreespond à aucun protocole.
+
+ + Attributes (object)
+ - error : `Object not found.`
+
+
+### Créer une nouvelle révision du protocole [POST]
+
+Permet de créer une nouvelle révision du protocole.
+
+L'attribut `revision` doit être le dernier numéro de révision du protocole.
+
+La liste des métacatégorie doit être complête et remplacera la liste existante sur la révision courante.
+Tous les attributs d'une metacategories doivent être fournis à part `id`, `revision` et `base`.
+Les rêgles pour ces derniers sont les suivantes
+
+- Si `id` est présent: l'attribut `revision` doit être fourni et correspondre à la dernière valeur pour cette méta-catégorie. Si un des attributs a été modifé, une nouvelle révision sera créee.
+- Si `id` n'est pas présent: 2 possibilités:
+ - `base` est présent: Dans ce cas une nouvelle famille de méta-catégorie est créé prenant pour base la métacatégorie dont l'ID est passé comme base. Si les attributs ne sont pas les mêmes, une nouvelle révision sera automatiquement créée, sinon, les attributs de la méta-catégorie de base sont copié dans une révision de base.
+ - `base` n'est pas présent: une nouvelle métacatégorie est créée ainsi qu'une nouvelle famille de méta-catégorie basée dessus.
+
+Dans tous les cas, le retours est une sérialisation complête du protocole d'annotation, avec les nouveaux `id` et `revision` pour les méta-catégories créées ou mis à jour.
+
++ Parameters
+
+ + id: `a4977c1f-4752-4aff-b724-eec4033af25c` - Identifiant d'un protocole
+
++ Request (application/json)
+
+ + Headers
+
+ Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
+
+ + Attributes
+ - Include ProtocolRevision
+ - metacategories (array[MetacategoryRevision])
+
+
++ Response 201 (application/json)
+
+ + Attributes (ProtocolRevisionFull)
+
++ Response 403
+
+ Retournée si l'utilisateur (application) n'est pas le propriétaire du protocole.
+
+ + Attributes (object)
+ - error : `Application is not protocol owner.`
+
++ Response 409
+
+ Retournée si la valeur de l'attribut `revision` n'est pas le numéro de version courant du protocole, ou bien d'une des méta-catégories.
+
+ + Attributes (object)
+ - error : `Bad revision number.`
+
+
+## Détail d'un protocole [/protocol/{id}/{revision}/]
+
+### Voir une revision d'un protocole [GET]
+
+Permet d'obtenir la représentation complète d'une révision de protocole.
+
++ Parameters
+
+ + id: `a4977c1f-4752-4aff-b724-eec4033af25c` - Identifiant d'un protocole
+ + revision: `2` (number) - Numéro de la révision
+
++ Response 200 (application/json)
+
+ + Attributes (ProtocolRevisionFull)
+
++ Response 403
+
+ Retournée si l'utilisateur (application) n'est pas le propriétaire du protocole.
+
+ + Attributes (object)
+ - error : `Application is not protocol owner.`
+
++ Response 404
+
+ Retournée si l'un des paramêtre est érroné et qu'aucun objet ne correspond.
+
+ + Attributes (object)
+ - error : `Object not found.`
+
+
+
+## Détail méta-catégorie [/protocol/{protocol_id}/{revision}/metacategory/{metacategory_id}/]
+
+### Voir le détail d'une méta-catégorie [GET]
+
+Permet d'obtenir la représentation d'une révision de métacatégorie.
+
++ Parameters
+
+ + protocol_id: `a4977c1f-4752-4aff-b724-eec4033af25c` - Identifiant d'un protocole
+ + revision: `2` (number) - Numéro de la révision
+ + metacategory_id: `e5712a76-857a-4769-b27e-a3ac3fb38b4d` - Identifiant d'une méta-categorie
+
++ Response 200 (application/json)
+
+ + Attributes (MetacategoryRevision)
+
++ Response 403
+
+ Retournée si l'utilisateur (application) n'est pas le propriétaire du protocole.
+
+ + Attributes (object)
+ - error : `Application is not protocol owner.`
+
++ Response 404
+
+ Retournée si l'un des paramêtre est érroné et qu'aucun objet ne correspond.
+
+ + Attributes (object)
+ - error : `Object not found.`
+