API Aquila PRO V1

Cette page décrit les principaux endpoints de l’édition PRO. Ils sont exposés via une API HTTP (FastAPI).

Base URL

L’API est généralement exposée derrière un reverse proxy HTTPS, par exemple :

• https://aquila.example.com (production)
• https://aquila-recette.example.com (recette)

Les exemples ci‑dessous supposent que l’API est exposée sur le chemin racine.

1. GET /health

Vérifie la santé de l’agent PRO.

Exemple de réponse :

{
  "status": "ok",
  "service": "aquila-governance-v1",
  "edition": "PRO",
  "edition_version": "pro_v1.0.0"
}

2. GET /agent/status

Retourne l’état métier de l’agent PRO :

• type d’édition ;
• version ;
• informations de licence (sans données sensibles) ;
• nombre de projets/pipelines chargés.

Exemple de réponse :

{
  "service": "aquila-governance-v1",
  "edition": "PRO",
  "edition_version": "pro_v1.0.0",
  "licence": {
    "valid": true,
    "customer": "Entreprise X",
    "expires_at": "2026-12-31T23:59:59Z"
  },
  "stats": {
    "projects_loaded": 12,
    "pipelines_loaded": 24
  }
}

3. POST /agent/publish

Endpoint principal : une demande de pipeline appelle cette route pour obtenir une décision.

Exemple de requête :

{
  "repository": "org/service-api",
  "branch": "main",
  "pipeline": "deploy-prod",
  "metadata": {
    "run_id": "123456789",
    "initiator": "github-actions"
  }
}

Exemple de réponse :

{
  "status": "accepted",
  "reasons": [],
  "project": "service-api",
  "pipeline": "deploy-prod",
  "branch": "main"
}

ou, en cas de refus :

{
  "status": "refused",
  "reasons": [
    {
      "code": "branch_not_allowed",
      "message": "La branche 'feature/xyz' n'est pas autorisée pour ce pipeline."
    }
  ],
  "project": "service-api",
  "pipeline": "deploy-prod",
  "branch": "feature/xyz"
}

4. GET /agent/history

Permet de consulter l’historique des décisions. Les filtres usuels :

• période temporelle (date de début / fin) ;
• projet, pipeline, branche ;
• statut (accepted / refused).

Exemple d’appel :

GET /agent/history?repository=org/service-api&pipeline=deploy-prod&limit=50

Exemple de réponse (abrégée) :

{
  "items": [
    {
      "timestamp": "2025-11-19T10:15:00Z",
      "status": "accepted",
      "repository": "org/service-api",
      "pipeline": "deploy-prod",
      "branch": "main"
    }
  ]
}

5. GET /agent/projects

Retourne la liste des projets et pipelines connus de l’agent PRO.

Exemple de réponse :

{
  "projects": [
    {
      "name": "service-api",
      "repository": "org/service-api",
      "pipelines": ["build", "test", "deploy-prod"]
    }
  ]
}

6. GET /agent/stats

Fournit des statistiques agrégées :

• nombre total de demandes ;
• taux d’acceptation / refus ;
• répartition par projet/pipeline.

Exemple (simplifié) :

{
  "total_requests": 120,
  "accepted": 100,
  "refused": 20
}

7. GET /metrics

Expose les métriques Prometheus. Les noms exacts des métriques peuvent varier, mais on retrouve en général :

• aquila_publish_requests_total ;
• aquila_publish_refused_total ;
• aquila_cooldown_active_total ;
• aquila_projects_loaded.

Cette route est typiquement consommée par Prometheus et ne nécessite pas d’être exposée publiquement.