1 # Renkan API Documentation

     2 

     3 Ce document présente le fonctionnement et les différentes méthodes de l'API Renkan, basée sur DjangoRestFramework

     4 

     5 ### Objets manipulés et représentation en JSON

     6 

     7 ##### Renkan

     8 

     9 L'objet Renkan est le principal point d'entrée de l'API.    

    10 Chaque Renkan est associé à au plus un workspace et au moins une révision

    11 

    12 * Représentation JSON   

    13 

    14 ```sh

    15     {

    16         "id" : id du renkan,

    17         "title" : titre du renkan,

    18         "content" : contenu (JSON) du renkan,

    19         "current_revision_id" : id de la révision courante du 	renkan,

    20         "source_revision_id" : id de la révision ayant servi à copier le renkan, chaîne vide sinon,

    21         "workspace_id" : si le renkan est assigné à un workspace, id du workspace du renkan,

    22         "revision_count": le nombre de révisions du renkan au moment du la requête,

    23         "created_by" : username du créateur du renkan,

    24         "last_updated_by" : username du dernier utilisateur à avoir modifié le renkan,

    25         "creation_date" : date de création du renkan,

    26         "modification_date" : date de dernière modification du renkan,

    27     }

    28 ```

    29 

    30 ##### Révisions

    31 

    32 Une révision représente l'état d'un renkan à un instant donné.    

    33 Chaque révision est associé à un unique Renkan. Lorsqu'un renkan est modifié, on peut soit altérer la révision courante, soit créer une nouvelle révision. La dernière révision d'un renkan donné créée est la "révision courante" de ce renkan.    

    34 

    35 C'est au niveau de l'objet Révision que sont stockées les informations de titre et de contenu d'un Renkan. 

    36 

    37 * Représentation JSON   

    38 

    39 ```sh

    40     {

    41     	"id" : id de la revision

    42     	"title" : titre de la revision

    43     	"content" : contenu (JSON) de la revision

    44     	"parent_renkan_id" : id du renkan associé à la révision 

    45     	"workspace_id" : si le renkan associé à la révision est assigné à un workspace, 

    46     	id du workspace du renkan,

    47     	"renkan_created_by" : username du créateur du renkan

    48     	"renkan_last_updated_by" : username du dernier utilisateur à avoir modifié le renkan

    49     	"revision_created_by" : username du créateur de la révision

    50     	"revision_last_updated_by" : username du dernier utilisateur à avoir modifié la révision	

    51     	"revision_modification_date" :  date de dernière modification de la révision

    52     }

    53 ```

    54 

    55 ##### Workspaces

    56 Un workspace (ou espace) renkan est une structure (optionnelle) regroupant un ou plusieurs renkans. 

    57 

    58 * Représentation JSON   

    59 

    60 ```sh

    61    {

    62     	"id" : id du workspace

    63     	"title" : titre du workspace

    64     	"renkan_count": nombre de renkans associés au workspace

    65     	"revision_created_by" : username du créateur du workspace

    66     	"creation_date": date de création du workspace

    67     }

    68 ```

    69 

    70 ### Liste exhaustive des endpoints de l'API

    71 

    72 #### Endpoints Renkan

    73 1. **Créer un Renkan**    

    74 ```POST /renkan-api/renkans/```

    75 

    76 Données à passer en JSON (facultatif):

    77 ```

    78     {

    79 	    "title": titre du renkan à créer (facultatif)

    80 	    "content": JSON du renkan à créer (facultatif)

    81     }

    82 ```

    83 

    84 **Note:** Si aucun titre n'est fournie le renkan sera intitulé "Untitled Renkan". Si aucun contenu n'est fourni un JSON minimal sera généré

    85 

    86 Si succès: Renvoie ```201 CREATED``` et le json associé au renkan créé

    87 

    88 2. **Dupliquer un Renkan**    

    89 ```POST /renkan-api/renkans/?source_renkan_id=<:renkan_id>```    

    90 

    91 Données à passer en JSON:

    92 ```

    93 {

    94 	"title": titre de la copie (facultatif)

    95 }

    96 ```    

    97 

    98 **Note:** Dans l'implémentation actuelle, si la donnée "title" n'est pas fournie, le titre du renkan copié sera identique au titre du renkan source.

    99 

   100 Si succès: renvoie ```201 CREATED``` et le json décrivant le renkan créé.    

   101 Si échec: renvoie un ```404 NOT FOUND``` si ```<:renkan_id>``` ne correspond à aucun renkan existant

   102 

   103 3. **Modifier un Renkan**    

   104 ```PUT /renkan-api/renkans/<:renkan_id>```

   105 

   106 Données à passer en JSON:

   107 ```

   108 {

   109 	"title": nouveau titre du renkan

   110 }

   111 ```

   112 

   113 Si succès: renvoie ```200 OK``` et le json associé au renkan modifié    

   114 Si échec:  renvoie un ```404 NOT FOUND``` si ```<:renkan_id>``` ne correspond à aucun renkan existant.

   115 

   116 4. **Obtenir la liste des Renkan**  

   117 ```GET /renkan-api/renkans/```

   118 

   119 Renvoie la liste des renkans auxquels l'utilisateur authentifié a accès en lecture.

   120 

   121 Si succès: Renvoie ```200 OK```et une liste où chaque élément correspond à un json de renkan.

   122 

   123 5. **Obtenir les informations sur un Renkan**    

   124 ```GET /renkan-api/renkans/<:renkan_id>```    

   125 

   126 Si succès: renvoie ```200 OK``` et le json associé au renkan requêté    

   127 Si échec: renvoie ```404 NOT FOUND``` si ```<:renkan_id>``` ne correspond à aucun renkan existant.

   128 

   129 6. **Supprimer un renkan**  

   130 ```DELETE /renkan-api/renkans/<:renkan_id>```

   131 

   132 Si succès: renvoie ```204 NO CONTENT```     

   133 Si échec: renvoie un ```404 NOT FOUND``` si ```<:renkan_id>``` ne correspond à aucun renkan existant.

   134 

   135 #### Endpoints Révision

   136 1. **Obtenir la liste des révisions pour un Renkan donné**	

   137 ```GET /renkan-api/renkans/<:renkan_id>/revisions/```

   138 

   139 Si succès: Renvoie ```200 OK``` et une liste où chaque élément est un json correspondant à une révision.    

   140 Si échec: Renvoie un ```404 NOT FOUND``` si le ```<:renkan_id>``` ne correspond à aucun renkan existant

   141 

   142 2. **Obtenir les informations sur une révision**    

   143 ```GET /renkan-api/renkans/<:renkan_id>/revisions/<:revision_id>```

   144 

   145 Si succès: renvoie ```200 OK``` et le json associé à la révision requêtée     

   146 Si échec: renvoie un ```404 NOT FOUND``` si ```<:renkan_id>``` ne correspond à aucun renkan existant ou que ```<:revision_id>``` ne correspond à aucune révision existante.

   147 

   148 3. **Supprimer une révision**   

   149 ```DELETE /renkan-api/renkans/<:renkan_id>/revisions/<:revision_id>```

   150 

   151 **Note:** il est impossible de supprimer la "révision courante" d'un renkan.

   152 

   153 Si succès: renvoie ```204 NO CONTENT```  

   154 Si échec: renvoie un ```404 NOT FOUND``` si ```<:renkan_id>``` ne correspond à aucun renkan existant ou si ```<:revision_id>``` ne correspond à aucune révision existante

   155 

   156 #### Endpoints Workspace

   157 1. **Créer un Workspace**   

   158 ```POST /renkan-api/workspaces/```

   159 

   160 Données à fournir en JSON (facultatif):

   161 ``` 

   162 {

   163     "title": titre du workspace à créer

   164 }

   165 ```

   166 

   167 Si succès: Renvoie ```201 CREATED``` et le json associé au workspace créé

   168 

   169 2. **Créer un Renkan dans un Workspace donné**  

   170 ```POST /renkan-api/workspaces/<:workspace_id>/renkans/```

   171 

   172 Données (facultatif):

   173 ```

   174 {

   175 	"title": titre du renkan à créer (facultatif)

   176 	"content": JSON du renkan à créer (facultatif)

   177 }

   178 ```

   179 

   180 **Note:** Si aucun titre n'est fournie le renkan sera intitulé "Untitled Renkan". Si aucun contenu n'est fourni un JSON minimal sera généré

   181 

   182 Si succès: Renvoie ```201 CREATED``` et le json associé au renkan créé  

   183 Si échec: Renvoie un ```404 NOT FOUND``` si le ```<:workspace_id>``` ne correspond à aucun workspace exis-tant

   184 

   185 3. **Obtenir la liste des Workspaces**  

   186 ```GET /renkan-api/workspaces/ ```

   187 

   188 Si succès: renvoie ```200 OK``` et une liste où chaque élément est un json correspondant à un workspace.

   189 

   190 4. **Obtenir la liste des Renkan associé à un Workspace donné**     

   191 ```GET /renkan-api/workspace/<:workspace_id>/renkans/```

   192 

   193 Renvoie la liste des renkans (associés au workspace) auxquels l'utilisateur authentifié a accès en lecture.

   194 

   195 Si succès: Renvoie ```200 OK``` et une liste où chaque élément correspond à un json de renkan.    

   196 Si échec: Renvoie un ```404 NOT FOUND``` si le ```<:workspace_id>``` ne correspond à aucun workspace exis-tant

   197 

   198 5. **Obtenir les informations sur un Workspace**    

   199 ```GET /renkan-api/workspaces/```

   200 

   201 Si succès:renvoie ```200 OK``` et une liste où chaque élément est un json correspondant à un workspace.    

   202 Si échec: renvoie un ```404 NOT FOUND``` si le ```<:workspace_id>``` ne correspond à aucun workspace existant

   203 

   204 6. **Supprimer un Workspace**   

   205 ```DELETE /renkan-api/workspaces/<:workspace_id>```

   206 

   207 Note: il est impossible de supprimer un workspace s'il reste au moins un renkan assigné à celui-ci.

   208 

   209 Si succès: renvoie ```204 NO CONTENT```     

   210 Si échec: renvoie un ```404 NOT FOUND``` si le ```<:workspace_id>``` ne correspond à aucun workspace existant 

   211 

   212