diff --git a/Apps/Api.md b/Apps/Api.md index 511cc94..1496c5c 100644 --- a/Apps/Api.md +++ b/Apps/Api.md @@ -27,4 +27,111 @@ Il suffit d'ajouter le préfixe `/api/` pour arriver sur ces pages. * `treasury/remittance` (liste des différentes remises enregistrées) * `permission/permission` (liste de toutes les permissions enregistrées) * `permission/roles` (liste des permissions octroyées pour chacun des rôles) -* `logs` (liste des modifications enregistrées en base de données) \ No newline at end of file +* `logs` (liste des modifications enregistrées en base de données) + +## Utilisation de l'API + +La page `/api//` affiche la liste de tous les éléments enregistrés. La page `/api///` affiche les attributs d'un objet uniquement. + +L'affichage des données peut se faire sous deux formes : via une interface HTML propre ou directement en affichant le JSON brut. Le changement peut se faire en ajoutant en paramètre de l'URL `format=json` ou `format=api`, ou bien en plaçant en en-tête de la requête `Accept: application/json` ou `text/html`. + +L'API Web propose des formulaires facilitant l'ajout et la modification d'éléments. + +### GET + +Une requête GET affiche un ou des éléments. Si on veut la liste de tous les éléments d'un modèle, la réponse est de cette forme : + +```json +{ + "count": , + "next": "/api//?page=", + "previous": "/api//?page=", + "results": [ ... ] +} +``` +Où `` est le nombre d'éléments trouvés. La page n'affiche les informations que 20 par 20 pour ne pas augmenter inutilement la taille de la réponse. Les champs `next` et `previous` contiennent les URL des pages suivantes et précédentes (`null` si première ou dernière page). Le champ `results` contient enfin l'ensemble des objets trouvés, au format JSON. + +Certaines pages disposent de filtres, permettant de sélectionner les objets recherchés. Par exemple, il est possible de chercher une note d'un certain type matchant avec un certain alias. + +Le résultat est déjà par défaut filtré : seuls les éléments que l'utilisateur à le droit de voir sont affichés. Cela est possible grâce à la structure des permissions, générant justement des filtres de requêtes de base de données. + +Une requête à l'adresse `/api//pk/` affiche directement les informations du modèle demandé au format JSON. + +### POST + +Une requête POST permet d'ajouter des éléments. Cette requête n'est possible que sur la page `/api//`, la requête POST n'est pas supportée sur les pages de détails (car cette requête permet ... l'ajout). + +Des exceptions sont faites sur certaines pages : les pages de logs et de contenttypes sont en lecture uniquement. + +Les formats supportés sont multiples : `application/json`, `application/x-www-url-encoded`, `multipart/form-data`. Cela facilite l'envoi de requêtes. Le module construit ensuite l'instance du modèle et le sauvegarde dans la base de données. L'application `permission` s'assure que l'utilisateur à le droit de faire ce type de modification. La réponse renvoyée est l'objet enregistré au format JSON si l'ajout s'est bien déroulé, sinon un message d'erreur au format JSON. + +### PATCH + +Une requête PATCH permet de modifier un élément. Ce type de requête n'est disponible que sur la page de détails d'un élément : `/api//pk/`. + +Comme pour la requête POST, les formats supportés sont multiples : `application/json`, `application/x-www-url-encoded`, `multipart/form-data`. + +Il n'est pas utile d'indiquer tous les champs du modèle : seuls ceux qui sont à modifier suffisent. + +Attention : pour les modèles polymorphiques (`Note`, `Transaction`), il faut toujours spécifier le type de modèle pour que l'API arrive à s'y retrouver. Par exemple, si on veut rendre la transaction n°42 non valide, on effectue une requête `PATCH` sur `/api/note/transaction/transaction/42/` avec les données suivantes : + +```json +{ + "valid": false, + "resourcetype": "RecurrentTransaction" +} +``` + +### PUT + +Une requête PUT permet de remplacer un élément. Ce type de requête n'est disponible que sur la page de détails d'un élément : `/api//pk/`. + +Comme pour les requêtes POST ou PATCH, les formats supportés sont multiples : `application/json`, `application/x-www-url-encoded`, `multipart/form-data`. + +Contrairement à la requête PATCH, l'intégralité du modèle est remplacé. L'ancien modèle est détruit, on en recrée un nouveau avec la même clé primaire. Le fonctionnement est similaire à une requête POST. + +### DELETE + +Une requête de type DELETE permet de supprimer un élément. Ce type de requête n'est disponible que sur la page de détails d'un élément : `/api//pk/`. + +Aucune donnée n'est nécessaire. Le module de permissions vérifiera que la suppression est possible. Une erreur est sinon renvoyée. + +### OPTIONS + +Une reqête OPTIONS affiche l'ensemble des opérations possibles sur un modèle ou une instance. Prototype d'une réponse : + +```json +{ + "name": "", + "description": "", + "renders": [ + "application/json", + "text/html" + ], + "parses": [ + "application/json", + "application/x-www-form-urlencoded", + "multipart/form-data" + ], + "actions": { + "": { + "": { + "type": , + "required": , + "read_only": , + "label": "