From b44ff2a68e3d4590c269a08ca25b0b4fc24155b8 Mon Sep 17 00:00:00 2001
From: William Petit <wpetit@cadoles.com>
Date: Sat, 8 Jul 2023 12:19:43 -0600
Subject: [PATCH] doc: add proxy http api reference

---
 doc/README.md                  |   1 +
 doc/fr/references/admin_api.md | 182 +++++++++++++++++++++++++++++++++
 2 files changed, 183 insertions(+)
 create mode 100644 doc/fr/references/admin_api.md

diff --git a/doc/README.md b/doc/README.md
index d2cc1b7..2b579d5 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -10,6 +10,7 @@
 
 - [(FR) - Layers](./fr/references/layers/README.md)
 - [(FR) - Fichier de configuration](../misc/packaging/common/config.yml)
+- [(FR) - API d'administration](./fr/references/admin_api.md)
 
 ## Tutoriels
 
diff --git a/doc/fr/references/admin_api.md b/doc/fr/references/admin_api.md
new file mode 100644
index 0000000..e602d52
--- /dev/null
+++ b/doc/fr/references/admin_api.md
@@ -0,0 +1,182 @@
+# API d'administration
+
+## Authentification
+
+L'ensemble des appels aux APIs HTTP du service `bouncer-admin` sont authentifiées via l'utilisation d'un jeton [JWT](https://datatracker.ietf.org/doc/html/rfc7519) signé par la clé privée du serveur.
+
+Le jeton d'accès doit être transmis avec l'ensemble des appels aux points d'entrée via l'entête HTTP `Authorization` en respectant la forme suivante:
+
+```
+Authorization: Bearer <jwt>
+```
+
+### Génération d'un jeton d'authentification
+
+La génération d'un jeton d'authentification s'effectue via la commande suivante:
+
+```shell
+bouncer auth create-token --subject "<subject>" --role "<role>"
+```
+
+Où:
+
+- `"<subject>"` est une chaîne de caractère arbitraire ayant pour objectif d'identifier de manière unique l'utilisateur associé au jeton;
+- `"<role>"` peut prendre une des deux valeurs `reader` ou `writer` correspondant aux droits suivants respectifs:
+    - droit en lecture sur l'ensemble des entités (proxy, layer);
+    - droit en lecture ET en écriture sur l'ensemble des entités.
+
+
+## Points d'entrée
+
+### `POST /api/v1/proxies`
+
+Créer un nouveau proxy
+
+#### Exemple de corps de requête
+
+```json5
+{
+  "name": "myproxy",                // OBLIGATOIRE - Nom du proxy
+  "to": "https://www.cadoles.com",  // OBLIGATOIRE - Site distant ciblé par le proxy
+  "from": ["*"]                     // OPTIONNEL - Liste de patrons de filtrage associés au proxy
+}
+```
+
+#### Exemple de résultat
+
+```json5
+{
+    "data": {
+        "proxy": {
+            "name": "myproxy",
+            "weight": 0,
+            "enabled": false,
+            "to": "https://www.cadoles.com",
+            "from": ["*"],
+            "createdAt": "2018-12-10T13:45:00.000Z",
+            "updatedAt": "2018-12-10T13:45:00.000Z"
+        }
+    }
+}
+```
+
+#### Source
+
+Voir [`internal/admin/proxy_route.go#createProxy()`](../../../internal/admin/proxy_route.go#createProxy)
+
+### `GET /api/v1/proxies/{proxyName}`
+
+Récupérer les informations complètes sur un proxy
+
+#### Paramètres
+
+- `{proxyName}` - Nom du proxy
+
+#### Exemple de résultat
+
+```json5
+{
+    "data": {
+        "proxy": {
+            "name": "myproxy",
+            "weight": 0,
+            "enabled": false,
+            "to": "https://www.cadoles.com",
+            "from": ["*"],
+            "createdAt": "2018-12-10T13:45:00.000Z",
+            "updatedAt": "2018-12-10T13:45:00.000Z"
+        }
+    }
+}
+```
+
+#### Source
+
+Voir [`internal/admin/proxy_route.go#getProxy()`](../../../internal/admin/proxy_route.go#getProxy)
+
+### `PUT /api/v1/proxies/{proxyName}`
+
+Modifier un proxy
+
+#### Exemple de corps de requête
+
+```json5
+{
+  "to": "https://www.cadoles.com",  // OPTIONNEL - Site distant ciblé par le proxy
+  "from": ["mylocalproxydomain:*"], // OPTIONNEL - Liste de patrons de filtrage associés au proxy
+  "weight": 100,                    // OPTIONNEL - Poids à associer au proxy
+  "enabled": true,                  // OPTIONNEL - Activer/désactiver le proxy
+}
+```
+
+#### Exemple de résultat
+
+```json5
+{
+    "data": {
+        "proxy": {
+            "name": "myproxy",
+            "weight": 100,
+            "enabled": true,
+            "to": "https://www.cadoles.com",
+            "from": ["mylocalproxydomain:*"],
+            "createdAt": "2018-12-10T13:45:00.000Z",
+            "updatedAt": "2020-10-02T15:09:00.000Z"
+        }
+    }
+}
+```
+
+#### Source
+
+Voir [`internal/admin/proxy_route.go#updateProxy()`](../../../internal/admin/proxy_route.go#updateProxy)
+
+### `GET /api/v1/proxies?names={name1,name2,...}`
+
+Lister les proxies existants
+
+#### Paramètres
+
+- `{names}` - Optionnel - Liste des noms de proxy à appliquer en tant que filtre
+
+#### Exemple de résultat
+
+```json5
+{
+    "data": {
+        "proxies": [
+            {
+                "name": "myproxy",
+                "weight": 0,
+                "enabled": false,
+            }
+        ]
+    }
+}
+```
+
+#### Source
+
+Voir [`internal/admin/proxy_route.go#queryProxy()`](../../../internal/admin/proxy_route.go#queryProxy)
+
+## `DELETE /api/v1/proxies/{proxyName}`
+
+Supprimer le proxy
+
+#### Paramètres
+
+- `{proxyName}` - Nom du proxy
+
+#### Exemple de résultat
+
+```json5
+{
+    "data": {
+        "proxyName": "myproxy"
+    }
+}
+```
+
+#### Source
+
+Voir [`internal/admin/proxy_route.go#deleteProxy()`](../../../internal/admin/proxy_route.go#deleteProxy)