From 15ecef3d84305c3ad18a13c9e2a78a8dfc917000 Mon Sep 17 00:00:00 2001
From: Alexandre Aubin <alexandre.aubin@cern.ch>
Date: Thu, 3 Jan 2019 17:44:33 +0100
Subject: [PATCH] Translate and improve admin_api doc

---
 admin_api.md    | 55 +++++++++++++++++++++++++++++++++++++++++++++++++
 admin_api_fr.md | 34 ++++++++++++++++++++++--------
 2 files changed, 80 insertions(+), 9 deletions(-)
 create mode 100644 admin_api.md

diff --git a/admin_api.md b/admin_api.md
new file mode 100644
index 00000000..b0861691
--- /dev/null
+++ b/admin_api.md
@@ -0,0 +1,55 @@
+# Administration from the API or an external application
+
+All command line actions can also be ran from the web API. The API is available at https://your.server/yunohost/api. For now there's no documentation on the various routes ... but you can get an idea by looking at the actionmap [here](https://github.com/YunoHost/yunohost/blob/stretch-unstable/data/actionsmap/yunohost.yml) (in particular the `api` stuff).
+
+## Using `curl`
+
+You must first retrieve a login cookie to perform the actions. Here is an example via curl:
+
+```bash
+# Login (with admin password)
+curl -k -H "X-Requested-With: customscript" \
+        -d "password=supersecretpassword" \
+        -dump-header headers \
+        https://your.server/yunohost/api/login
+
+# GET example
+curl -k -i -H "Accept: application/json" \
+           -H "Content-Type: application/json" \
+           -L -b headers -X GET https://your.server/yunohost/api/ROUTE \
+        | grep } | python -mjson.tool
+```
+
+## Using a PHP class
+
+To simplify the remote administration of a YunoHost instance in CHATONS/Librehosters projects, API classes have been developed by users.
+
+For example, this PHP class (FIXME: where are people supposed to find it..?) will allow you to administer your YunoHost instance from a PHP application (website, capacity management tool...).
+
+Here is an example of PHP code to add a user to your YunoHost instance:
+
+```php 
+require("ynh_api.class.php");
+$ynh = new YNH_API("adresse IP du serveur YunoHost ou nom d’hôte", "mot de passe administrateur");
+
+if ($ynh->login()) {
+    $domains = $ynh->get("/domains");
+    $first_domain = $domains['domains'][0];
+
+    $arguments = array(
+        'username' => 'test',
+        'password' => 'yunohost', 
+        'firstname' => 'Prénom',
+        'lastname' => 'Nom',
+        'mail' => 'test@'.$first_domain,
+        'mailbox_quota' => '500M'
+    );
+
+    $user_add = $ynh->post("/users", $arguments);
+    print_r($user_add);
+
+} else {
+    print("Login to YunoHost failed.\n");
+    exit;
+}
+```
diff --git a/admin_api_fr.md b/admin_api_fr.md
index a31ce4e1..5a6e7cc1 100644
--- a/admin_api_fr.md
+++ b/admin_api_fr.md
@@ -1,21 +1,36 @@
 # Administration depuis l’API ou une application externe
 
-Toutes les actions exécutables en ligne de commande le sont également via une API.
+Toutes les actions exécutables en ligne de commande le sont également via une API. L’API est accessible à l’adresse https://votre.serveur/yunohost/api.
+Pour le moment, il n'existe pas de documentation des différentes routes ... mais
+vous pouvez trouver l'actionmap [ici](https://github.com/YunoHost/yunohost/blob/stretch-unstable/data/actionsmap/yunohost.yml) (en particulier les clefs `api`)
 
-L’API utilise l’adresse https://VOTRESERVEUR/yunohost/api et toutes les actions sont détaillées sur cette page.
+## Avec `curl`
 
 Il faut d’abord récupérer un cookie de connexion pour ensuite réaliser les actions. Voici un exemple via curl :
-```bash
-    Login (avec mot de passe admin): curl -k  -H “X-Requested-With: customscript” -d “password=XXX” –dump-header headers https://VOTRESERVEUR/yunohost/api/login
-    GET: curl -k -i -H “Accept: application/json” -H “Content-Type: application/json” -L -b headers -X GET https://VOTRESERVEUR/yunohost/api/ROUTE | grep }| python -mjson.tool
-```
-Pour simplifier l’administration à distance d’une instance YunoHost dans le cadre d’un projet CHATONS, des classes API ont été développées par des utilisateurs.
 
-Par exemple, cette classe PHP vous permettra d’administrer votre instance YunoHost depuis une application PHP (site web, outil de gestion de capacité…).
+```bash
+# Login (avec mot de passe admin)
+curl -k -H "X-Requested-With: customscript" \
+        -d "password=supersecretpassword" \
+        -dump-header headers \
+        https://your.server/yunohost/api/login
+
+# Example de GET
+curl -k -i -H "Accept: application/json" \
+           -H "Content-Type: application/json" \
+           -L -b headers -X GET https://your.server/yunohost/api/ROUTE \
+        | grep } | python -mjson.tool
+```
+
+# Avec une classe PHP
+
+Pour simplifier l’administration à distance d’une instance YunoHost dans le cadre d’un projet CHATONS/Librehosters, des classes API ont été développées par des utilisateurs.
+
+Par exemple, cette classe PHP (FIXME: où la trouver...?) vous permettra d’administrer votre instance YunoHost depuis une application PHP (site web, outil de gestion de capacité…).
 
 Voici un exemple de code PHP permettant d’ajouter un utilisateur dans votre instance YunoHost :
 
-```bash 
+```php
 require("ynh_api.class.php");
 $ynh = new YNH_API("adresse IP du serveur YunoHost ou nom d’hôte", "mot de passe administrateur");
 
@@ -40,3 +55,4 @@ if ($ynh->login()) {
     exit;
 }
 ```
+