sdk_storage/docs/api_json_spec.md

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)

{
  "$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)

{
  "$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)

{
  "$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.