Structures de Réponse API

Ce document détaille les structures de réponse JSON réelles retournées par l'API Sharokey pour tous les SDKs (Python, JavaScript, CLI), basées sur l'implémentation de l'API Laravel.

Format de Réponse Commun

Toutes les méthodes API retournent des dictionnaires JSON avec cette structure du trait ApiResponse :

json

{
  "success": boolean,
  "message": "string (optionnel)",
  "data": object | array,
  "meta": {
    "version": "v1",
    "timestamp": "2024-01-15T10:30:00.000000Z"
  }
}

Opérations de Secrets

Réponse Créer un Secret

Retournée par client.create() (depuis SecretController@store lignes 282-302) :

json

{
  "success": true,
  "message": "Secret créé avec succès",
  "data": {
    "slug": "ABC123XY",
    "description": "Identifiants base de données",
    "message": "Manipuler avec précaution",
    "creator": "[email protected]",
    "maximum_views": 3,
    "current_views": 0,
    "expires_in_hours": 24,
    "expiration": "2024-01-16T10:30:00.000000Z",
    "has_password": true,
    "has_captcha": false,
    "has_otp": false,
    "has_ip_restriction": true,
    "has_geo_restriction": false,
    "has_attachments": true,
    "attachments_count": 2,
    "is_expired": false,
    "status": "active",
    "access_url": "https://app.sharokey.com/ABC123XY",
    "created_at": "2024-01-15T10:30:00.000000Z"
  },
  "meta": {
    "version": "v1",
    "timestamp": "2024-01-15T10:30:00.000000Z"
  }
}

Réponse Obtenir un Secret

Retournée par client.get(slug) (depuis SecretController@show lignes 338-363) :

json

{
  "success": true,
  "data": {
    "slug": "ABC123XY",
    "description": "Identifiants base de données",
    "message": "Manipuler avec précaution", 
    "creator": "[email protected]",
    "maximum_views": 3,
    "current_views": 1,
    "expiration": "2024-01-16T10:30:00.000000Z",
    "has_password": true,
    "has_attachments": true,
    "attachments": [
      {
        "name": "contrat.pdf"
      },
      {
        "name": "specifications.docx"
      }
    ],
    "captcha": false,
    "otp_type": null,
    "ip_whitelist": "192.168.1.0/24",
    "geolocation": null,
    "is_expired": false,
    "status": "active",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T16:15:00.000000Z"
  },
  "meta": {
    "version": "v1",
    "timestamp": "2024-01-15T17:30:00.000000Z"
  }
}

Réponse Lister les Secrets

Retournée par client.list(), client.search(), client.get_active_secrets() (depuis SecretController@index lignes 125-129) :

json

{
  "success": true,
  "count": 42,
  "secrets": [
    {
      "slug": "ABC123XY",
      "description": "Identifiants base de données",
      "message": "Manipuler avec précaution",
      "creator": "[email protected]",
      "maximum_views": 1,
      "current_views": 0,
      "expires_in_hours": 24,
      "expiration": "2024-01-16T10:30:00.000000Z",
      "has_password": false,
      "has_captcha": false,
      "has_otp": false,
      "has_ip_restriction": false,
      "has_geo_restriction": false,
      "has_attachments": false,
      "attachments_count": 0,
      "is_expired": false,
      "status": "active",
      "created_at": "2024-01-15T10:30:00.000000Z"
    },
    {
      "slug": "XYZ789AB",
      "description": "Identifiants API",
      "message": "Valable jusqu'à la fin du projet",
      "creator": "[email protected]",
      "maximum_views": 5,
      "current_views": 2,
      "expires_in_hours": 48,
      "expiration": "2024-01-17T10:30:00.000000Z",
      "has_password": true,
      "has_captcha": false,
      "has_otp": true,
      "has_ip_restriction": false,
      "has_geo_restriction": true,
      "has_attachments": true,
      "attachments_count": 1,
      "is_expired": false,
      "status": "active",
      "created_at": "2024-01-15T08:45:00.000000Z"
    }
  ],
  "meta": {
    "version": "v1",
    "timestamp": "2024-01-15T17:30:00.000000Z"
  }
}

Réponse Supprimer un Secret

Retournée par client.delete(slug) (depuis SecretController@destroy ligne 484) :

json

{
  "success": true,
  "message": "Secret supprimé avec succès",
  "meta": {
    "version": "v1",
    "timestamp": "2024-01-15T17:30:00.000000Z"
  }
}

Statistiques

Réponse Statistiques

Retournée par client.stats() (depuis SecretController@stats lignes 501-533) :

json

{
  "success": true,
  "message": "Statistiques des secrets récupérées avec succès",
  "data": {
    "total_secrets": 125,
    "active_secrets": 48,
    "expired_secrets": 77,
    "total_views": 892,
    "secrets_with_password": 23,
    "secrets_created_today": 5,
    "secrets_created_this_week": 18,
    "secrets_created_this_month": 47
  },
  "meta": {
    "version": "v1",
    "timestamp": "2024-01-15T17:30:00.000000Z"
  }
}

Requêtes de Secrets

Note : Les structures SecretRequestController seront documentées séparément basées sur l'implémentation réelle du contrôleur.

Réponses d'Erreur

Erreur de Validation (422)

Depuis ApiResponse@validationErrorResponse :

json

{
  "success": false,
  "message": "Échec de la validation",
  "errors": {
    "content": ["Le contenu est requis et ne peut pas être vide"],
    "expiration_hours": ["Les heures d'expiration doivent être entre 1 et 1000"],
    "maximum_views": ["Les vues maximum doivent être entre 1 et 10"]
  },
  "meta": {
    "version": "v1",
    "timestamp": "2024-01-15T17:30:00.000000Z"
  }
}

Erreur d'Authentification (401)

json

{
  "success": false,
  "message": "Non autorisé",
  "meta": {
    "version": "v1",
    "timestamp": "2024-01-15T17:30:00.000000Z"
  }
}

Erreur Interdite (403)

json

{
  "success": false,
  "message": "Permissions insuffisantes pour créer des secrets",
  "meta": {
    "version": "v1",
    "timestamp": "2024-01-15T17:30:00.000000Z"
  }
}

Erreur Non Trouvée (404)

json

{
  "success": false,
  "message": "Secret non trouvé",
  "meta": {
    "version": "v1",
    "timestamp": "2024-01-15T17:30:00.000000Z"
  }
}

Erreur Serveur (500)

json

{
  "success": false,
  "message": "Échec de la création du secret",
  "meta": {
    "version": "v1",
    "timestamp": "2024-01-15T17:30:00.000000Z"
  }
}

Quota Dépassé (429)

json

{
  "success": false,
  "message": "Vous avez atteint le nombre maximum de secrets autorisés pour votre plan actuel.",
  "meta": {
    "version": "v1",
    "timestamp": "2024-01-15T17:30:00.000000Z"
  }
}

Exemples d'Utilisation

Accès aux Données de Réponse

python

# Créer un secret
response = await client.create("Mon secret", 24, 1)
if response['success']:
    secret_data = response['data']
    share_url = secret_data['access_url']
    print(f"Secret créé : {share_url}")

# Lister les secrets
response = await client.list(limit=10)
if response['success']:
    total_count = response['count']
    secrets = response['secrets']
    print(f"Trouvé {total_count} secrets au total")
    
    for secret in secrets:
        views_info = f"{secret['current_views']}/{secret['maximum_views']}"
        status = secret['status']
        print(f"- {secret['slug']}: {secret['description']} ({views_info} vues, {status})")

# Obtenir les statistiques
response = await client.stats()
if response['success']:
    stats = response['data']
    print(f"Total : {stats['total_secrets']}")
    print(f"Actifs : {stats['active_secrets']}")
    print(f"Aujourd'hui : {stats['secrets_created_today']}")

# Gérer les erreurs
try:
    response = await client.create("", 24, 1)  # Contenu vide
except ValidationError as e:
    print(f"Erreur de validation : {e}")
    # La réponse API réelle contiendrait les détails de validation dans le champ 'errors'

Descriptions des Champs

Champs de Secret

Champ	Type	Description
`slug`	string	Identifiant unique de secret à 8 caractères
`description`	string\|null	Description fournie par l'utilisateur (max 255 caractères)
`message`	string\|null	Message montré au visualiseur du secret (max 255 caractères)
`creator`	string	Email du créateur ou "API" pour les tokens d'entreprise
`maximum_views`	int\|null	Vues maximum autorisées (1-10)
`current_views`	int	Nombre de fois où le secret a été visualisé
`expires_in_hours`	int	Heures jusqu'à expiration (1-1000)
`expiration`	string\|null	Horodatage d'expiration ISO 8601
`has_password`	boolean	Si le secret a une protection par mot de passe
`has_captcha`	boolean	Si le secret nécessite un CAPTCHA
`has_otp`	boolean	Si le secret nécessite une vérification OTP
`has_ip_restriction`	boolean	Si le secret a une liste blanche IP
`has_geo_restriction`	boolean	Si le secret a une restriction de géolocalisation
`has_attachments`	boolean	Si le secret a des pièces jointes
`attachments_count`	int	Nombre de fichiers attachés
`is_expired`	boolean	Si le secret est expiré
`status`	string	"active" ou "expired"
`access_url`	string	URL complète pour accéder au secret
`created_at`	string	Horodatage de création ISO 8601

Toutes les structures de réponse sont basées sur l'implémentation réelle de l'API Laravel et reflètent les vraies réponses JSON de l'API Sharokey. 📊

Structures de Réponse API ​

Format de Réponse Commun ​

Opérations de Secrets ​

Réponse Créer un Secret ​

Réponse Obtenir un Secret ​

Réponse Lister les Secrets ​

Réponse Supprimer un Secret ​

Statistiques ​

Réponse Statistiques ​

Requêtes de Secrets ​

Réponses d'Erreur ​

Erreur de Validation (422) ​

Erreur d'Authentification (401) ​

Erreur Interdite (403) ​

Erreur Non Trouvée (404) ​

Erreur Serveur (500) ​

Quota Dépassé (429) ​

Exemples d'Utilisation ​

Accès aux Données de Réponse ​

Descriptions des Champs ​

Champs de Secret ​

Structures de Réponse API

Format de Réponse Commun

Opérations de Secrets

Réponse Créer un Secret

Réponse Obtenir un Secret

Réponse Lister les Secrets

Réponse Supprimer un Secret

Statistiques

Réponse Statistiques

Requêtes de Secrets

Réponses d'Erreur

Erreur de Validation (422)

Erreur d'Authentification (401)

Erreur Interdite (403)

Erreur Non Trouvée (404)

Erreur Serveur (500)

Quota Dépassé (429)

Exemples d'Utilisation

Accès aux Données de Réponse

Descriptions des Champs

Champs de Secret