docs: api json spec

docs/README.md

@@ -23,6 +23,7 @@ Voir aussi:
 - `developpement.md`
 - `depannage.md`
 - `performance.md`
+- `api_json_spec.md`
 
 ## REX technique
 

docs/api_json_spec.md

@@ -0,0 +1,109 @@
+# Spécification JSON des API
+
+## Généralités
+- Content-Type: `application/json; charset=utf-8`
+- Encodage des valeurs: chaînes hexadécimales minuscules (0-9a-f).
+- Modèle d'erreur: corps `{ "message": string }` avec code HTTP approprié.
+
+## POST /store
+- Objet requête: `StoreRequest`
+- Objet réponse (succès/erreur): `ApiResponse`
+
+### Schéma JSON (StoreRequest)
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "StoreRequest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["key", "value"],
+  "properties": {
+    "key": {
+      "type": "string",
+      "description": "Clé hexadécimale 64 caractères (32 octets).",
+      "pattern": "^[0-9a-fA-F]{64}$"
+    },
+    "value": {
+      "type": "string",
+      "description": "Valeur encodée en hexadécimal.",
+      "pattern": "^[0-9a-fA-F]+$"
+    },
+    "ttl": {
+      "type": "integer",
+      "minimum": 60,
+      "maximum": 31536000,
+      "description": "Durée de vie en secondes. Si absent: défaut 86400 sauf si mode --permanent (aucune expiration)."
+    }
+  }
+}
+```
+
+### Règles de validation et sémantique
+- `key`: exactement 64 caractères hex (
+32 octets).
+- `value`: chaîne hex valide, longueur paire recommandée (représentation d'octets).
+- `ttl`:
+  - min: 60, max: 31 536 000.
+  - si absent et binaire lancé sans `--permanent`: valeur par défaut 86 400.
+  - si absent et binaire lancé avec `--permanent`: aucune expiration.
+
+### Réponses
+- 200 OK: `ApiResponse` (message de succès)
+- 400 Bad Request: `ApiResponse` (clé/ttl/valeur invalides)
+- 409 Conflict: `ApiResponse` (clé déjà existante)
+- 500 Internal Server Error: `ApiResponse`
+
+### Schéma JSON (ApiResponse)
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ApiResponse",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["message"],
+  "properties": {
+    "message": { "type": "string" }
+  }
+}
+```
+
+## GET /retrieve/:key
+- Paramètre de chemin: `key` (hex 64).
+- Objet réponse (succès): `RetrieveResponse`
+- Objet réponse (erreur): `ApiResponse`
+
+### Contraintes
+- `key` doit respecter `^[0-9a-fA-F]{64}$`.
+
+### Réponses
+- 200 OK: `RetrieveResponse`
+- 400 Bad Request: `ApiResponse` (clé invalide)
+- 404 Not Found: `ApiResponse` (clé inconnue)
+- 500 Internal Server Error: `ApiResponse`
+
+### Schéma JSON (RetrieveResponse)
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RetrieveResponse",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["key", "value"],
+  "properties": {
+    "key": {
+      "type": "string",
+      "description": "Clé hexadécimale 64 caractères.",
+      "pattern": "^[0-9a-fA-F]{64}$"
+    },
+    "value": {
+      "type": "string",
+      "description": "Valeur encodée en hexadécimal.",
+      "pattern": "^[0-9a-fA-F]+$"
+    }
+  }
+}
+```
+
+## Codes d'état et messages
+- Les messages d'erreur sont informatifs mais ne divulguent pas d'informations sensibles.
+- Les champs `message` sont destinés à l'humain; ne pas les parser côté client.