110 lines
3.0 KiB
Markdown
110 lines
3.0 KiB
Markdown
# 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.
|