Documentation API

L'API REST SQL Audit vous permet d'intégrer vos audits SQL Server dans vos pipelines CI/CD, scripts de monitoring et outils d'automatisation.

Authentification

Toutes les requêtes API nécessitent une clé API valide

Obtenez une clé API depuis votre tableau de bord. Incluez-la dans le header X-API-Key de chaque requête.

Exemple d'authentification

curl -X GET "https://audit.databreizh.fr/api/v1/instances" \
  -H "X-API-Key: sqla_votre_cle_api"

Sécurité des clés API

Ne partagez jamais vos clés API. Stockez-les dans des variables d'environnement ou des gestionnaires de secrets. Révoquez immédiatement toute clé compromise.

Limites de taux

L'API est limitée à 100 requêtes par minute par clé API. Les headers suivants indiquent l'état de votre quota :

Header	Description
X-RateLimit-Limit	Nombre maximum de requêtes par fenêtre
X-RateLimit-Remaining	Requêtes restantes dans la fenêtre actuelle
X-RateLimit-Reset	Date/heure de réinitialisation du compteur (ISO 8601)

Format des réponses

Toutes les réponses suivent un format JSON standardisé :

Réponse réussie

{
  "success": true,
  "data": {
    // Données de la réponse
  },
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 20,
    "total_pages": 3
  }
}

Réponse d'erreur

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Instance non trouvé",
    "details": null
  }
}

Testez toujours error.code, jamais error.message : le code est stable, le message est de la prose destinée à un humain et peut changer sans préavis.

Langue des libellés

Les charges d'exemple de cette page montrent la réponse par défaut

Les libellés du catalogue (check_name, check_description, check_remediation, category_name) sont servis dans la langue de la requête par /api/v1/checks et /api/v1/instances/{id}/findings. La langue est déduite dans cet ordre : cookie NEXT_LOCALE, en-tête Referer, en-tête Accept-Language, puis français par défaut — un appel curl qui ne porte aucun des trois reçoit donc du français.

Obtenir les libellés en anglais

curl -X GET "https://audit.databreizh.fr/api/v1/checks?category=security" \
  -H "X-API-Key: sqla_votre_cle_api" \
  -H "Accept-Language: en"

Endpoints

GET
`/api/v1/instances`

Liste toutes vos instances SQL Server

Paramètres

Nom	Type	Description
`page`	integer	Numéro de page (défaut: 1)
`per_page`	integer	Résultats par page (défaut: 20, max: 100)
`environment`	string	Filtrer par environnement (production, staging, development)
`min_score`	integer	Score global minimum
`max_score`	integer	Score global maximum

Exemple

curl -X GET "https://audit.databreizh.fr/api/v1/instances?environment=production" \
  -H "X-API-Key: sqla_votre_cle_api"

Réponse

{
  "success": true,
  "data": {
    "instances": [
      {
        "id": "uuid",
        "name": "PROD-SQL01",
        "hostname": "prod-sql01.local",
        "version": "SQL Server 2022",
        "edition": "Enterprise",
        "environment": "production",
        "score_global": 82,
        "score_security": 75,
        "score_configuration": 88,
        "score_files": 92,
        "score_backups": 90,
        "score_maintenance": 85,
        "score_agent": 78,
        "score_performance": 80,
        "score_reliability": 87,
        "score_updates": 70,
        "score_hardware": 95,
        "score_io": 82,
        "score_memory": 88,
        "score_queries": 72,
        "score_storedprocs": 90,
        "score_connections": 85,
        "score_dblevel": 78,
        "score_wait_statistics": 80,
        "score_query_store": 75,
        "score_linked_servers": 92,
        "score_blocking": 88,
        "score_db_settings": 82,
        "score_extended_events": 70,
        "score_encryption": 85,
        "score_capacity": 90,
        "score_database_mail": 78,
        "checks_total": 110,
        "checks_passed": 60,
        "checks_failed": 8,
        "checks_warning": 7,
        "last_audit_at": "2024-01-15T10:30:00Z",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ]
  },
  "meta": { "total": 5, "page": 1, "per_page": 20 }
}

GET
`/api/v1/instances/{id}`

Détails d'une instance spécifique avec historique des audits

Paramètres

Nom	Type	Description
`id`*	uuid	ID de l'instance (dans l'URL)

Exemple

curl -X GET "https://audit.databreizh.fr/api/v1/instances/instance-uuid" \
  -H "X-API-Key: sqla_votre_cle_api"

Réponse

{
  "success": true,
  "data": {
    "instance": {
      "id": "uuid",
      "name": "PROD-SQL01",
      "hostname": "prod-sql01.local",
      "version": "SQL Server 2022",
      "edition": "Enterprise",
      "score_global": 82,
      // ... tous les scores par catégorie
    },
    "audits": [
      {
        "id": "audit-uuid",
        "score_global": 82,
        "collected_at": "2024-01-15T10:30:00Z",
        "checks_total": 110,
        "checks_passed": 60,
        "checks_failed": 8
      }
    ]
  }
}

GET
`/api/v1/instances/{id}/findings`

Liste des findings du dernier audit d'une instance

Paramètres

Nom	Type	Description
`id`*	uuid	ID de l'instance (dans l'URL)
`category`	string	Filtrer par catégorie (security, backups, performance, etc.)
`status`	string	Filtrer par statut (pass, fail, warning, info)
`severity`	string	Filtrer par sévérité (critical, high, medium, low, info)
`page`	integer	Numéro de page
`per_page`	integer	Résultats par page

Exemple

curl -X GET "https://audit.databreizh.fr/api/v1/instances/uuid/findings?status=fail&severity=critical" \
  -H "X-API-Key: sqla_votre_cle_api"

Réponse

{
  "success": true,
  "data": {
    "findings": [
      {
        "id": "finding-uuid",
        "check_id": "SEC001",
        "category_id": "security",
        "status": "fail",
        "severity": "critical",
        "value": "1",
        "details": "Le compte SA est activé",
        "check_name": "Compte SA activé",
        "check_description": "Le compte SA doit être désactivé",
        "check_remediation": "ALTER LOGIN sa DISABLE",
        "category_name": "Sécurité",
        "category_color": "#ef4444"
      }
    ],
    "audit_id": "audit-uuid"
  },
  "meta": { "total": 8, "page": 1, "per_page": 20 }
}

POST
`/api/v1/upload`
Scope: write

Upload un fichier CSV d'audit

Paramètres

Nom	Type	Description
`file`*	file	Fichier CSV (multipart/form-data) ou body text/csv

Exemple

# Avec multipart/form-data
curl -X POST "https://audit.databreizh.fr/api/v1/upload" \
  -H "X-API-Key: sqla_votre_cle_api" \
  -F "file=@audit_PROD-SQL01_2024-01-15.csv"

# Avec raw CSV
curl -X POST "https://audit.databreizh.fr/api/v1/upload" \
  -H "X-API-Key: sqla_votre_cle_api" \
  -H "Content-Type: text/csv" \
  --data-binary @audit.csv

Réponse

{
  "success": true,
  "data": {
    "instance_id": "uuid",
    "audit_id": "audit-uuid",
    "instance": {
      "name": "PROD-SQL01",
      "version": "SQL Server 2022",
      "hostname": "prod-sql01.local"
    },
    "stats": {
      "total": 75,
      "passed": 60,
      "failed": 8,
      "warnings": 7,
      "info": 0
    },
    "score": 82
  }
}

GET
`/api/v1/checks`

Catalogue complet des checks disponibles

Paramètres

Nom	Type	Description
`category`	string	Filtrer par catégorie
`severity`	string	Filtrer par sévérité
`enabled_only`	boolean	Uniquement les checks actifs (défaut: true)
`page`	integer	Numéro de page
`per_page`	integer	Résultats par page

Exemple

curl -X GET "https://audit.databreizh.fr/api/v1/checks?category=security" \
  -H "X-API-Key: sqla_votre_cle_api"

Réponse

{
  "success": true,
  "data": {
    "checks": [
      {
        "id": "SEC001",
        "category_id": "security",
        "name": "Compte SA activé",
        "description": "Le compte SA doit être désactivé",
        "severity": "critical",
        "points_deduction": 20,
        "remediation": "ALTER LOGIN sa DISABLE",
        "doc_url": "https://learn.microsoft.com/...",
        "category_name": "Sécurité",
        "category_color": "#ef4444"
      }
    ],
    "categories": [
      {
        "id": "security",
        "name": "Sécurité",
        "description": "...",
        "icon": "shield",
        "color": "#ef4444",
        "weight": 15
      }
    ]
  },
  "meta": { "total": 75, "page": 1, "per_page": 20 }
}

Codes d'erreur

Code	HTTP	Description
UNAUTHORIZED	401	Clé API invalide ou manquante
FORBIDDEN	403	Scope insuffisant pour cette opération
NOT_FOUND	404	Ressource non trouvée
BAD_REQUEST	400	Requête mal formée
VALIDATION_ERROR	422	Erreur de validation des données
RATE_LIMITED	429	Quota de requêtes dépassé
SERVER_ERROR	500	Erreur serveur interne

Référence complète (OpenAPI 3.1)

Cette page présente les endpoints de base. Les imports idempotents (POST /api/v1/imports), les webhooks signés (/api/v1/webhooks) et le reporting d'organisation (/api/v1/reports/*) sont décrits dans le document OpenAPI, source de vérité de l'API.

Télécharger le document OpenAPI (YAML)

Besoin d'aide ? Contactez-nous à contact@databreizh.fr

Documentation API

Authentification

Limites de taux

Format des réponses

Langue des libellés

Endpoints

GET/api/v1/instances

Paramètres

Exemple

Réponse

GET/api/v1/instances/{id}

Paramètres

Exemple

Réponse

GET/api/v1/instances/{id}/findings

Paramètres

Exemple

Réponse

POST/api/v1/uploadScope: write

Paramètres

Exemple

Réponse

GET/api/v1/checks

Paramètres

Exemple

Réponse

Codes d'erreur

Référence complète (OpenAPI 3.1)

GET
`/api/v1/instances`

GET
`/api/v1/instances/{id}`

GET
`/api/v1/instances/{id}/findings`

POST
`/api/v1/upload`
Scope: write

GET
`/api/v1/checks`